@saptools/cf-debugger 0.2.0 → 0.2.2

package/dist/{chunk-ZWAQD7KL.js → chunk-QBB4N2WN.js}

@@ -12,6 +12,32 @@ var CfDebuggerError = class extends Error {
   }
 };
 
+// src/input-validation.ts
+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 validateCfCliOperand(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `${label} must be a non-empty string.`);
+  }
+  if (value.trim() !== value) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `${label} must not contain surrounding whitespace.`);
+  }
+  if (value.startsWith("-")) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `${label} must not start with a hyphen.`);
+  }
+  if (hasControlCharacter(value)) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `${label} must not contain control characters.`);
+  }
+  return value;
+}
+
 // src/regions.ts
 var REGION_KEY_PATTERN = /^[a-z]{2}\d{2}(?:-\d{3})?$/;
 var REGION_API_ENDPOINTS = {
@@ -80,9 +106,61 @@ function synthesizeApiEndpoint(regionKey) {
   const domain = regionKey.startsWith("cn") ? "platform.sapcloud.cn" : "hana.ondemand.com";
   return `https://api.cf.${regionKey}.${domain}`;
 }
+function rejectApiEndpoint(raw, reason) {
+  return new CfDebuggerError(
+    "UNSAFE_INPUT",
+    `Invalid --api-endpoint ${JSON.stringify(raw)}: ${reason}. Expected an absolute https URL such as https://api.cf.<region>.hana.ondemand.com.`
+  );
+}
+function validateApiEndpointOverride(raw) {
+  if (typeof raw !== "string") {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "Invalid --api-endpoint value: it must be a string."
+    );
+  }
+  const value = raw.trim();
+  if (value.length === 0) {
+    throw rejectApiEndpoint(raw, "the value is empty or whitespace only");
+  }
+  if (value !== raw) {
+    throw rejectApiEndpoint(raw, "it contains surrounding whitespace");
+  }
+  if (value.startsWith("-")) {
+    throw rejectApiEndpoint(raw, "a leading hyphen would be parsed as a cf CLI flag");
+  }
+  if (hasControlCharacter(value)) {
+    throw rejectApiEndpoint(raw, "it contains control characters");
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw rejectApiEndpoint(raw, "it is not a parseable absolute URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw rejectApiEndpoint(
+      raw,
+      `the scheme must be https, not ${parsed.protocol.replace(":", "")} (credentials are sent to this endpoint)`
+    );
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    throw rejectApiEndpoint(raw, "it must not embed userinfo credentials");
+  }
+  if (parsed.search !== "" || parsed.hash !== "") {
+    throw rejectApiEndpoint(raw, "it must not carry a query string or fragment");
+  }
+  if (parsed.pathname !== "" && parsed.pathname !== "/") {
+    throw rejectApiEndpoint(raw, "it must not carry a path");
+  }
+  if (parsed.hostname === "") {
+    throw rejectApiEndpoint(raw, "it has no host");
+  }
+  return value;
+}
 function resolveApiEndpoint(regionKey, override, onWarning) {
-  if (override !== void 0 && override !== "") {
-    return override;
+  if (override !== void 0) {
+    return validateApiEndpointOverride(override);
   }
   if (!REGION_KEY_PATTERN.test(regionKey)) {
     throw new CfDebuggerError(
@@ -110,6 +188,8 @@ import nodeProcess from "process";
 var MAX_BUFFER = 16 * 1024 * 1024;
 var DEFAULT_CF_COMMAND_TIMEOUT_MS = 6e4;
 var DEFAULT_CF_OPERATION_TIMEOUT_MS = 3e5;
+var MUTATING_CF_ATTEMPT_TIMEOUT_MS = 18e4;
+var MUTATION_DIAGNOSTIC_RESERVE_MS = 250;
 var REDACTED_ARG = "<redacted>";
 var MAX_RETRY_DELAY_MS = 1e4;
 function buildEnv(cfHome) {
@@ -159,12 +239,12 @@ function optionalString(value) {
 }
 function readFailureDetails(error) {
   const object = typeof error === "object" && error !== null ? error : void 0;
-  const field3 = (key) => object === void 0 ? void 0 : Reflect.get(object, key);
+  const field4 = (key) => object === void 0 ? void 0 : Reflect.get(object, key);
   return {
-    code: optionalString(field3("code")),
-    killed: field3("killed") === true,
+    code: optionalString(field4("code")),
+    killed: field4("killed") === true,
     message: error instanceof Error ? error.message : String(error),
-    stderr: optionalString(field3("stderr"))
+    stderr: optionalString(field4("stderr"))
   };
 }
 function hasTransientDiagnostic(error) {
@@ -268,57 +348,72 @@ function signalCfChild(child, signal) {
   } catch {
   }
 }
+function rejectBoundedExecution(settlement, cleanup, reject, failure) {
+  if (settlement.settled) {
+    return;
+  }
+  settlement.settled = true;
+  cleanup();
+  reject(failure);
+}
+function handleBoundedCompletion(settlement, cleanup, resolve, reject, signal, error, stdout, stderr) {
+  if (settlement.settled) {
+    return;
+  }
+  if (error === null && signal?.aborted !== true) {
+    settlement.settled = true;
+    cleanup();
+    resolve({ stderr, stdout });
+    return;
+  }
+  const failure = error ?? new Error("Command was aborted.");
+  Reflect.set(failure, "stderr", stderr);
+  rejectBoundedExecution(settlement, cleanup, reject, failure);
+}
+function terminateBoundedExecution(settlement, cleanup, reject, child, code, message) {
+  if (settlement.settled) {
+    return;
+  }
+  signalCfChild(child, "SIGKILL");
+  child.stdout?.destroy();
+  child.stderr?.destroy();
+  const failure = new Error(message);
+  Reflect.set(failure, "code", code);
+  Reflect.set(failure, "killed", true);
+  Reflect.set(failure, "stderr", "");
+  rejectBoundedExecution(settlement, cleanup, reject, failure);
+}
 async function executeFileBounded(command, args, options) {
   return await new Promise((resolve, reject) => {
-    let settled = false;
+    const settlement = { settled: false };
     const cleanup = () => {
       clearTimeout(timer);
       options.signal?.removeEventListener("abort", onAbort);
     };
-    const rejectOnce = (error) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      cleanup();
-      reject(error);
-    };
     const child = execFile(command, [...args], {
       env: options.env,
       maxBuffer: options.maxBuffer ?? MAX_BUFFER,
       encoding: "utf8"
     }, (error, stdout, stderr) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      cleanup();
-      if (error === null && options.signal?.aborted !== true) {
-        resolve({ stderr, stdout });
-        return;
-      }
-      const failure = error ?? new Error("Command was aborted.");
-      Reflect.set(failure, "stderr", stderr);
-      reject(failure);
+      handleBoundedCompletion(
+        settlement,
+        cleanup,
+        resolve,
+        reject,
+        options.signal,
+        error,
+        stdout,
+        stderr
+      );
     });
-    const terminateAndReject = (code, message) => {
-      if (settled) {
-        return;
-      }
-      signalCfChild(child, "SIGKILL");
-      child.stdout?.destroy();
-      child.stderr?.destroy();
-      const failure = new Error(message);
-      Reflect.set(failure, "code", code);
-      Reflect.set(failure, "killed", true);
-      Reflect.set(failure, "stderr", "");
-      rejectOnce(failure);
+    const terminate = (code, message) => {
+      terminateBoundedExecution(settlement, cleanup, reject, child, code, message);
     };
     const onAbort = () => {
-      terminateAndReject("ABORT_ERR", "Command was aborted.");
+      terminate("ABORT_ERR", "Command was aborted.");
     };
     const timer = setTimeout(() => {
-      terminateAndReject("ETIMEDOUT", "Command exceeded its execution deadline.");
+      terminate("ETIMEDOUT", "Command exceeded its execution deadline.");
     }, options.timeoutMs);
     options.signal?.addEventListener("abort", onAbort, { once: true });
     if (options.signal?.aborted) {
@@ -339,6 +434,13 @@ function createCfCliError(args, failure, redactionValues) {
     stderr
   );
 }
+function mutationTimeoutError(args, redactionValues) {
+  const verb = args[0] ?? "command";
+  return new CfDebuggerError(
+    "CF_MUTATION_TIMEOUT",
+    `cf ${formatArgsForError(args, redactionValues)} did not complete within its deadline and was not retried, because it mutates the deployed application. The ${verb} may still be completing on the platform; check the application state before retrying.`
+  );
+}
 function timeoutError(context, args, redactionValues) {
   if (context.deadlineAt !== void 0) {
     const timeoutMs = context.startupTimeoutMs;
@@ -361,46 +463,69 @@ function reportRetry(context, args, attempt, delayMs, remainingMs, redactionValu
     remainingMs
   });
 }
-async function runCf(args, context, input = {}) {
+function planCfAttempt(command, options, context) {
+  const remainingMs = options.deadlineAt - Date.now();
+  if (remainingMs <= 0) {
+    throw timeoutError(context, command.args, options.redactionValues);
+  }
+  const attemptCap = command.retryPolicy === "mutation" ? Math.min(MUTATING_CF_ATTEMPT_TIMEOUT_MS, options.attemptTimeoutMs * 3) : options.attemptTimeoutMs;
+  const attemptBudget = command.retryPolicy === "mutation" ? Math.max(1, remainingMs - MUTATION_DIAGNOSTIC_RESERVE_MS) : remainingMs;
+  return {
+    // A mutating child must time out before the overall startup signal so the
+    // user receives the specific "mutation may still be in flight" diagnostic.
+    timeoutMs: Math.max(1, Math.min(attemptCap, attemptBudget))
+  };
+}
+async function handleCfAttemptFailure(error, command, context, options, attempt, attemptTimeoutMs, startedAt) {
+  const failure = readFailureDetails(error);
+  if (context.signal?.aborted || failure.code === "ABORT_ERR") {
+    throw abortError(context);
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const attemptTimedOut = failure.killed && elapsedMs + 100 >= attemptTimeoutMs;
+  if (command.retryPolicy === "mutation") {
+    throw attemptTimedOut ? mutationTimeoutError(command.args, options.redactionValues) : createCfCliError(command.args, failure, options.redactionValues);
+  }
+  if (isCredentialRejection(command.args, failure) || !isTransientNetworkError(failure, attemptTimedOut)) {
+    throw createCfCliError(command.args, failure, options.redactionValues);
+  }
+  const delayMs = retryDelayMs(attempt);
+  const remainingMs = options.deadlineAt - Date.now();
+  if (remainingMs <= delayMs) {
+    throw timeoutError(context, command.args, options.redactionValues);
+  }
+  reportRetry(
+    context,
+    command.args,
+    attempt,
+    delayMs,
+    remainingMs,
+    options.redactionValues
+  );
+  await waitForRetry(delayMs, context);
+}
+async function runCf(command, context, input = {}) {
   if (context.signal?.aborted) {
     throw abortError(context);
   }
   const options = resolveRunOptions(context, input);
   let attempt = 0;
   for (; ; ) {
-    const remainingMs = options.deadlineAt - Date.now();
-    if (remainingMs <= 0) {
-      throw timeoutError(context, args, options.redactionValues);
-    }
+    const plan = planCfAttempt(command, options, context);
     attempt += 1;
-    const attemptTimeoutMs = Math.max(1, Math.min(options.attemptTimeoutMs, remainingMs));
     const startedAt = Date.now();
     try {
-      return await executeCfAttempt(args, context, options, attemptTimeoutMs);
+      return await executeCfAttempt(command.args, context, options, plan.timeoutMs);
     } catch (error) {
-      const failure = readFailureDetails(error);
-      if (context.signal?.aborted || failure.code === "ABORT_ERR") {
-        throw abortError(context);
-      }
-      const elapsedMs = Date.now() - startedAt;
-      const attemptTimedOut = failure.killed && elapsedMs + 100 >= attemptTimeoutMs;
-      if (isCredentialRejection(args, failure) || !isTransientNetworkError(failure, attemptTimedOut)) {
-        throw createCfCliError(args, failure, options.redactionValues);
-      }
-      const delayMs = retryDelayMs(attempt);
-      const afterFailureMs = options.deadlineAt - Date.now();
-      if (afterFailureMs <= delayMs) {
-        throw timeoutError(context, args, options.redactionValues);
-      }
-      reportRetry(
+      await handleCfAttemptFailure(
+        error,
+        command,
         context,
-        args,
+        options,
         attempt,
-        delayMs,
-        afterFailureMs,
-        options.redactionValues
+        plan.timeoutMs,
+        startedAt
       );
-      await waitForRetry(delayMs, context);
     }
   }
 }
@@ -408,16 +533,22 @@ async function runCf(args, context, input = {}) {
 // src/cloud-foundry/commands.ts
 var CURRENT_TARGET_TIMEOUT_MS = 3e4;
 function rethrowControlFlowError(error) {
-  if (error instanceof CfDebuggerError && (error.code === "ABORTED" || error.code === "STARTUP_TIMEOUT")) {
+  if (error instanceof CfDebuggerError && (error.code === "ABORTED" || error.code === "CF_MUTATION_TIMEOUT" || error.code === "STARTUP_TIMEOUT")) {
     throw error;
   }
 }
 async function cfApi(apiEndpoint, context) {
-  await runCf(["api", apiEndpoint], context);
+  await runCf({
+    args: ["api", apiEndpoint],
+    retryPolicy: "retry-transient"
+  }, context);
 }
 async function cfAuth(email, password, context) {
   try {
-    await runCf(["auth"], context, {
+    await runCf({
+      args: ["auth"],
+      retryPolicy: "retry-transient"
+    }, context, {
       env: { CF_PASSWORD: password, CF_USERNAME: email },
       sensitiveValues: [email, password]
     });
@@ -447,7 +578,10 @@ async function cfLogin(apiEndpoint, email, password, context) {
 }
 async function cfTarget(org, space, context) {
   try {
-    await runCf(["target", "-o", org, "-s", space], context);
+    await runCf({
+      args: ["target", "-o", org, "-s", space],
+      retryPolicy: "retry-transient"
+    }, context);
   } catch (err) {
     rethrowControlFlowError(err);
     if (err instanceof CfDebuggerError) {
@@ -458,7 +592,10 @@ async function cfTarget(org, space, context) {
 }
 async function cfAppExists(appName, context) {
   try {
-    await runCf(["app", appName], context);
+    await runCf({
+      args: ["app", appName],
+      retryPolicy: "retry-transient"
+    }, context);
     return true;
   } catch (err) {
     rethrowControlFlowError(err);
@@ -471,7 +608,10 @@ async function cfAppExists(appName, context) {
 }
 async function cfSshEnabled(appName, context) {
   try {
-    const stdout = await runCf(["ssh-enabled", appName], context);
+    const stdout = await runCf({
+      args: ["ssh-enabled", appName],
+      retryPolicy: "retry-transient"
+    }, context);
     const normalized = stdout.toLowerCase();
     if (normalized.includes("ssh support is enabled")) {
       return "enabled";
@@ -487,7 +627,10 @@ async function cfSshEnabled(appName, context) {
 }
 async function cfEnableSsh(appName, context) {
   try {
-    await runCf(["enable-ssh", appName], context);
+    await runCf({
+      args: ["enable-ssh", appName],
+      retryPolicy: "mutation"
+    }, context);
   } catch (err) {
     rethrowControlFlowError(err);
     if (err instanceof CfDebuggerError) {
@@ -497,7 +640,10 @@ async function cfEnableSsh(appName, context) {
   }
 }
 async function cfRestartApp(appName, context) {
-  await runCf(["restart", appName], context);
+  await runCf({
+    args: ["restart", appName],
+    retryPolicy: "mutation"
+  }, context);
 }
 async function readCurrentCfTarget(options = {}) {
   try {
@@ -556,7 +702,7 @@ function parseTargetFields(stdout) {
         line.slice(0, separator).trim().toLowerCase(),
         line.slice(separator + 1).trim()
       ];
-    }).filter((field3) => field3 !== void 0)
+    }).filter((field4) => field4 !== void 0)
   );
 }
 function regionKeyForApiEndpoint(apiEndpoint) {
@@ -622,15 +768,6 @@ function resolveNodeTarget(input) {
   validateNodePid(input.nodePid);
   return input.nodePid === void 0 ? { process: processName, instance } : { process: processName, instance, nodePid: input.nodePid };
 }
-function hasControlCharacter(value) {
-  for (let index = 0; index < value.length; index += 1) {
-    const code = value.charCodeAt(index);
-    if (code < 32 || code === 127) {
-      return true;
-    }
-  }
-  return false;
-}
 function buildNodeInspectorCommand(nodePid, remotePort = DEFAULT_NODE_INSPECTOR_PORT) {
   validateNodePid(nodePid);
   validateRemotePort(remotePort);
@@ -845,14 +982,15 @@ var NODE_INSPECTOR_SCRIPT = [
 ].join("\n");
 
 // src/cloud-foundry/ssh.ts
-import { spawn } from "child_process";
-import nodeProcess2 from "process";
+import { spawn as spawn2 } from "child_process";
+import nodeProcess4 from "process";
 import { StringDecoder } from "string_decoder";
+
+// src/cloud-foundry/ssh-shared.ts
 var DEFAULT_MAX_OUTPUT_BYTES = 65536;
 var LIVE_LINE_LIMIT_BYTES = 65536;
 var MAX_REDACTION_OVERLAP_BYTES = 4096;
 var SENSITIVE_OUTPUT_OMITTED = "[diagnostic output omitted to protect a sensitive value]";
-var tunnelCaptures = /* @__PURE__ */ new WeakMap();
 function buildCfSshArgs(appName, target, tail) {
   const resolved = resolveNodeTarget(target);
   const processArgs = resolved.process === DEFAULT_CF_PROCESS ? [] : ["--process", resolved.process];
@@ -865,35 +1003,6 @@ function buildCfSshArgs(appName, target, tail) {
     ...tail
   ];
 }
-async function cfSshOneShot(appName, command, context, rawOptions = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
-  if (context.signal?.aborted || isDeadlineExpired(context)) {
-    throw sshAbortError(context);
-  }
-  const options = resolveSshOptions(rawOptions, context);
-  const args = buildCfSshArgs(appName, options.target, [
-    "--disable-pseudo-tty",
-    "-c",
-    command
-  ]);
-  return await runSshOneShot(args, context, options);
-}
-function resolveSshOptions(raw, context) {
-  const input = typeof raw === "number" ? { timeoutMs: raw } : raw;
-  const requestedTimeoutMs = input.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS;
-  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
-  if (!Number.isSafeInteger(requestedTimeoutMs) || requestedTimeoutMs <= 0) {
-    throw new CfDebuggerError("UNSAFE_INPUT", "timeoutMs must be a positive safe integer.");
-  }
-  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
-    throw new CfDebuggerError("UNSAFE_INPUT", "maxOutputBytes must be a positive safe integer.");
-  }
-  const remainingMs = context.deadlineAt === void 0 ? requestedTimeoutMs : Math.max(1, context.deadlineAt - Date.now());
-  return {
-    target: input,
-    timeoutMs: Math.min(requestedTimeoutMs, remainingMs),
-    maxOutputBytes
-  };
-}
 function createBoundedOutput() {
   return { chunks: [], bytes: 0, truncated: false };
 }
@@ -934,9 +1043,6 @@ function appendTail(output, data, outputLimit, retainedLimit) {
     }
   }
 }
-function outputText(output) {
-  return Buffer.concat(output.chunks, output.bytes).toString("utf8");
-}
 function createRedactionPolicy(values) {
   const sensitiveValues = normalizeSensitiveValues(values);
   const overlapBytes = sensitiveValues.reduce(
@@ -949,6 +1055,9 @@ function createRedactionPolicy(values) {
     overlapBytes: Math.min(overlapBytes, MAX_REDACTION_OVERLAP_BYTES)
   };
 }
+function outputText(output) {
+  return Buffer.concat(output.chunks, output.bytes).toString("utf8");
+}
 function limitText(text, limit, keep) {
   const buffer = Buffer.from(text);
   if (buffer.byteLength <= limit) {
@@ -964,37 +1073,6 @@ function safeOutputText(output, policy, limit, keep) {
   const redacted = redactSensitiveText(outputText(output), policy.sensitiveValues);
   return limitText(redacted, limit, keep);
 }
-function createResult(exitCode, state) {
-  const stdout = safeOutputText(state.stdout, state.redaction, state.outputLimit, "head");
-  const stderr = safeOutputText(state.stderr, state.redaction, state.outputLimit, "head");
-  return {
-    exitCode,
-    stdout,
-    stderr,
-    outputTruncated: state.stdout.truncated || state.stderr.truncated,
-    stdoutTruncated: state.stdout.truncated,
-    stderrTruncated: state.stderr.truncated
-  };
-}
-function createSshExecutionState(context, outputLimit) {
-  const redaction = createRedactionPolicy(context.sensitiveValues ?? []);
-  return {
-    stdout: createBoundedOutput(),
-    stderr: createBoundedOutput(),
-    outputLimit,
-    retainedLimit: outputLimit + redaction.overlapBytes,
-    redaction,
-    settled: false,
-    aborted: false,
-    timedOut: false
-  };
-}
-function terminateSshExecution(child, state) {
-  signalChild(child, "SIGTERM");
-  state.forceKillTimer ??= setTimeout(() => {
-    signalChild(child, "SIGKILL");
-  }, 1e3);
-}
 function sshAbortError(context) {
   if (context.deadlineAt !== void 0 && Date.now() >= context.deadlineAt) {
     return new CfDebuggerError(
@@ -1007,79 +1085,312 @@ function sshAbortError(context) {
 function isDeadlineExpired(context) {
   return context.deadlineAt !== void 0 && Date.now() >= context.deadlineAt;
 }
-function createSshSettler(state, options, context, onAbort, resolve, reject) {
-  return (result) => {
-    if (state.settled) {
-      return;
-    }
-    state.settled = true;
-    clearTimeout(state.timeoutTimer);
-    clearTimeout(state.forceKillTimer);
-    context.signal?.removeEventListener("abort", onAbort);
-    if (state.aborted) {
-      reject(sshAbortError(context));
-      return;
-    }
-    resolve(state.timedOut ? { ...result, timedOutAfterMs: options.timeoutMs } : result);
-  };
-}
-function attachSshExecution(child, context, options, resolve, reject) {
-  const state = createSshExecutionState(context, options.maxOutputBytes);
-  const onAbort = () => {
-    state.aborted = true;
-    terminateSshExecution(child, state);
-  };
-  const settle = createSshSettler(state, options, context, onAbort, resolve, reject);
-  state.timeoutTimer = setTimeout(() => {
-    state.timedOut = true;
-    terminateSshExecution(child, state);
-  }, options.timeoutMs);
-  if (context.signal?.aborted) {
-    onAbort();
-  } else {
-    context.signal?.addEventListener("abort", onAbort, { once: true });
+
+// src/cloud-foundry/ssh-one-shot.ts
+import {
+  spawn
+} from "child_process";
+import nodeProcess3 from "process";
+
+// src/debug-session/process-identity.ts
+import { execFile as execFile2 } from "child_process";
+import { readFile } from "fs/promises";
+import nodeProcess2 from "process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile2);
+var PROCESS_IDENTITY_VERSION = "v1";
+var DARWIN_START_TIME_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) +(?:[1-9]|[12]\d|3[01]) \d{2}:\d{2}:\d{2} \d{4}$/;
+function errorCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
   }
-  child.stdout.on("data", (data) => {
-    appendHead(state.stdout, data, state.outputLimit, state.retainedLimit);
-  });
-  child.stderr.on("data", (data) => {
-    appendHead(state.stderr, data, state.outputLimit, state.retainedLimit);
-  });
-  child.on("close", (code, signal) => {
-    const base = createResult(code, state);
-    settle(state.timedOut || signal === null ? base : { ...base, signal });
-  });
-  child.on("error", (error) => {
-    appendHead(state.stderr, error.message, state.outputLimit, state.retainedLimit);
-    settle(createResult(null, state));
-  });
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
 }
-function runSshOneShot(args, context, options) {
-  if (context.signal?.aborted || isDeadlineExpired(context)) {
-    return Promise.reject(sshAbortError(context));
+function parseLinuxProcessStartTime(statLine) {
+  const commandEnd = statLine.lastIndexOf(")");
+  if (commandEnd < 0) {
+    return void 0;
   }
-  return new Promise((resolve, reject) => {
-    const child = spawn(resolveBin(context), [...args], {
-      env: buildEnv(context.cfHome),
-      detached: nodeProcess2.platform !== "win32",
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    attachSshExecution(child, context, options, resolve, reject);
-  });
+  const fieldsAfterCommand = statLine.slice(commandEnd + 1).trim().split(/\s+/);
+  const startTime = fieldsAfterCommand[19];
+  return startTime !== void 0 && /^\d+$/.test(startTime) ? startTime : void 0;
 }
-function signalChild(child, signal) {
-  if (nodeProcess2.platform !== "win32" && child.pid !== void 0) {
-    try {
-      nodeProcess2.kill(-child.pid, signal);
-      return;
-    } catch {
-    }
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Process identity inspection was aborted.");
   }
+}
+async function linuxProcessIdentity(pid, signal) {
   try {
-    child.kill(signal);
-  } catch {
+    const statLine = await readFile(`/proc/${pid.toString()}/stat`, {
+      encoding: "utf8",
+      ...signal === void 0 ? {} : { signal }
+    });
+    const startTime = parseLinuxProcessStartTime(statLine);
+    return startTime === void 0 ? void 0 : `linux:${PROCESS_IDENTITY_VERSION}:${startTime}`;
+  } catch (error) {
+    throwIfAborted(signal);
+    if (errorCode(error) === "ENOENT") {
+      return void 0;
+    }
+    return void 0;
   }
 }
+function darwinIdentityEnvironment(environment) {
+  return {
+    ...environment,
+    LC_ALL: "C",
+    TZ: "UTC"
+  };
+}
+async function darwinProcessIdentity(pid, signal) {
+  try {
+    const { stdout } = await execFileAsync("ps", ["-p", pid.toString(), "-o", "lstart="], {
+      env: darwinIdentityEnvironment(nodeProcess2.env),
+      ...signal === void 0 ? {} : { signal },
+      timeout: 2e3
+    });
+    const startedAt = stdout.trim();
+    return startedAt.length === 0 ? void 0 : `darwin:${PROCESS_IDENTITY_VERSION}:${startedAt}`;
+  } catch {
+    throwIfAborted(signal);
+    return void 0;
+  }
+}
+async function readProcessIdentity(pid, signal) {
+  throwIfAborted(signal);
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    return void 0;
+  }
+  if (nodeProcess2.platform === "linux") {
+    return await linuxProcessIdentity(pid, signal);
+  }
+  if (nodeProcess2.platform === "darwin") {
+    return await darwinProcessIdentity(pid, signal);
+  }
+  return void 0;
+}
+function isCurrentProcessIdentity(identity) {
+  if (/^linux:v1:\d+$/.test(identity)) {
+    return true;
+  }
+  const darwinPrefix = `darwin:${PROCESS_IDENTITY_VERSION}:`;
+  return identity.startsWith(darwinPrefix) && DARWIN_START_TIME_PATTERN.test(identity.slice(darwinPrefix.length));
+}
+async function inspectProcessIdentity(pid, expected, signal) {
+  throwIfAborted(signal);
+  if (expected === void 0) {
+    return "match";
+  }
+  if (!isCurrentProcessIdentity(expected)) {
+    return "unavailable";
+  }
+  const current = await readProcessIdentity(pid, signal);
+  if (current === void 0 || !isCurrentProcessIdentity(current)) {
+    return "unavailable";
+  }
+  return current === expected ? "match" : "mismatch";
+}
+
+// src/cloud-foundry/ssh-one-shot.ts
+async function cfSshOneShot(appName, command, context, rawOptions = DEFAULT_CF_COMMAND_TIMEOUT_MS) {
+  if (context.signal?.aborted || isDeadlineExpired(context)) {
+    throw sshAbortError(context);
+  }
+  const options = resolveSshOptions(rawOptions, context);
+  const args = buildCfSshArgs(appName, options.target, [
+    "--disable-pseudo-tty",
+    "-c",
+    command
+  ]);
+  return await runSshOneShot(args, context, options);
+}
+function resolveSshOptions(raw, context) {
+  const input = typeof raw === "number" ? { timeoutMs: raw } : raw;
+  const requestedTimeoutMs = input.timeoutMs ?? DEFAULT_CF_COMMAND_TIMEOUT_MS;
+  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  if (!Number.isSafeInteger(requestedTimeoutMs) || requestedTimeoutMs <= 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "timeoutMs must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
+    throw new CfDebuggerError("UNSAFE_INPUT", "maxOutputBytes must be a positive safe integer.");
+  }
+  const remainingMs = context.deadlineAt === void 0 ? requestedTimeoutMs : Math.max(1, context.deadlineAt - Date.now());
+  return {
+    target: input,
+    timeoutMs: Math.min(requestedTimeoutMs, remainingMs),
+    maxOutputBytes
+  };
+}
+function createResult(exitCode, state) {
+  const stdout = safeOutputText(state.stdout, state.redaction, state.outputLimit, "head");
+  const stderr = safeOutputText(state.stderr, state.redaction, state.outputLimit, "head");
+  return {
+    exitCode,
+    stdout,
+    stderr,
+    outputTruncated: state.stdout.truncated || state.stderr.truncated,
+    stdoutTruncated: state.stdout.truncated,
+    stderrTruncated: state.stderr.truncated
+  };
+}
+function createSshExecutionState(context, outputLimit) {
+  const redaction = createRedactionPolicy(context.sensitiveValues ?? []);
+  return {
+    stdout: createBoundedOutput(),
+    stderr: createBoundedOutput(),
+    outputLimit,
+    retainedLimit: outputLimit + redaction.overlapBytes,
+    redaction,
+    settled: false,
+    aborted: false,
+    timedOut: false,
+    terminationStarted: false
+  };
+}
+function childIsOpen(child) {
+  return child.exitCode === null && child.signalCode === null;
+}
+async function captureSshChildIdentity(child) {
+  if (nodeProcess3.platform === "win32" || child.pid === void 0) {
+    return;
+  }
+  try {
+    return await readProcessIdentity(child.pid);
+  } catch {
+    return;
+  }
+}
+async function canSignalSshChild(child, childIdentity, signal) {
+  if (!childIsOpen(child) || child.pid === void 0) {
+    return false;
+  }
+  const expectedIdentity = await childIdentity;
+  if (expectedIdentity === void 0) {
+    return signal === "SIGTERM" && childIsOpen(child);
+  }
+  return await inspectProcessIdentity(child.pid, expectedIdentity) === "match" && childIsOpen(child);
+}
+function abandonUnverifiedSshChild(child) {
+  try {
+    child.stdout?.destroy();
+  } catch {
+  }
+  try {
+    child.stderr?.destroy();
+  } catch {
+  }
+  try {
+    child.unref();
+  } catch {
+  }
+}
+function terminateSshExecution(child, childIdentity, state, settle) {
+  if (state.settled || state.terminationStarted) {
+    return;
+  }
+  state.terminationStarted = true;
+  const settleUnverified = () => {
+    if (!state.settled) {
+      abandonUnverifiedSshChild(child);
+      settle(createResult(null, state));
+    }
+  };
+  void (async () => {
+    if (!await canSignalSshChild(child, childIdentity, "SIGTERM") || state.settled) {
+      settleUnverified();
+      return;
+    }
+    signalChild(child, "SIGTERM");
+    state.forceKillTimer = setTimeout(() => {
+      void (async () => {
+        if (!await canSignalSshChild(child, childIdentity, "SIGKILL") || state.settled) {
+          settleUnverified();
+          return;
+        }
+        signalChild(child, "SIGKILL");
+      })().catch(settleUnverified);
+    }, 1e3);
+  })().catch(settleUnverified);
+}
+function createSshSettler(state, options, context, onAbort, resolve, reject) {
+  return (result) => {
+    if (state.settled) {
+      return;
+    }
+    state.settled = true;
+    clearTimeout(state.timeoutTimer);
+    clearTimeout(state.forceKillTimer);
+    context.signal?.removeEventListener("abort", onAbort);
+    if (state.aborted) {
+      reject(sshAbortError(context));
+      return;
+    }
+    resolve(state.timedOut ? { ...result, timedOutAfterMs: options.timeoutMs } : result);
+  };
+}
+function attachSshExecution(child, childIdentity, context, options, resolve, reject) {
+  const state = createSshExecutionState(context, options.maxOutputBytes);
+  const onAbort = () => {
+    state.aborted = true;
+    terminateSshExecution(child, childIdentity, state, settle);
+  };
+  const settle = createSshSettler(state, options, context, onAbort, resolve, reject);
+  state.timeoutTimer = setTimeout(() => {
+    state.timedOut = true;
+    terminateSshExecution(child, childIdentity, state, settle);
+  }, options.timeoutMs);
+  if (context.signal?.aborted) {
+    onAbort();
+  } else {
+    context.signal?.addEventListener("abort", onAbort, { once: true });
+  }
+  child.stdout.on("data", (data) => {
+    appendHead(state.stdout, data, state.outputLimit, state.retainedLimit);
+  });
+  child.stderr.on("data", (data) => {
+    appendHead(state.stderr, data, state.outputLimit, state.retainedLimit);
+  });
+  child.on("close", (code, signal) => {
+    const base = createResult(code, state);
+    settle(state.timedOut || signal === null ? base : { ...base, signal });
+  });
+  child.on("error", (error) => {
+    appendHead(state.stderr, error.message, state.outputLimit, state.retainedLimit);
+    settle(createResult(null, state));
+  });
+}
+function runSshOneShot(args, context, options) {
+  if (context.signal?.aborted || isDeadlineExpired(context)) {
+    return Promise.reject(sshAbortError(context));
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(resolveBin(context), [...args], {
+      env: buildEnv(context.cfHome),
+      detached: nodeProcess3.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const childIdentity = captureSshChildIdentity(child);
+    attachSshExecution(child, childIdentity, context, options, resolve, reject);
+  });
+}
+function signalChild(child, signal) {
+  if (nodeProcess3.platform !== "win32" && child.pid !== void 0) {
+    try {
+      nodeProcess3.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
+
+// src/cloud-foundry/ssh.ts
+var tunnelCaptures = /* @__PURE__ */ new WeakMap();
 function isSshDisabledError(stderr) {
   return stderr.toLowerCase().includes("ssh support is disabled");
 }
@@ -1244,21 +1555,41 @@ 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], {
+  const child = spawn2(resolveBin(context), [...args], {
     env: buildEnv(context.cfHome),
-    detached: nodeProcess2.platform !== "win32",
+    detached: nodeProcess4.platform !== "win32",
     stdio: ["ignore", "pipe", "pipe"]
   });
   attachTunnelCapture(child, context);
   return child;
 }
 
+// src/restart-policy.ts
+function parseRestartEnvironment(value) {
+  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 applyRestartEnvironmentVeto(requested, value) {
+  return parseRestartEnvironment(value) === "forbid" ? false : requested === true;
+}
+
 // src/session-state/store.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { chmod as chmod3, mkdir as mkdir3, readFile as readFile4, rename, unlink as unlink3, writeFile as writeFile2 } from "fs/promises";
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { chmod as chmod3, mkdir as mkdir3, readFile as readFile5, rename, unlink as unlink3, writeFile as writeFile2 } from "fs/promises";
 import { hostname as getHostname2 } from "os";
 import { dirname as dirname2, isAbsolute as isAbsolute3 } from "path";
-import nodeProcess5 from "process";
+import nodeProcess6 from "process";
 
 // src/debug-session/constants.ts
 var DEFAULT_TUNNEL_READY_TIMEOUT_MS = 18e4;
@@ -1269,87 +1600,6 @@ var CHILD_SIGTERM_GRACE_MS = 2e3;
 var CHILD_SIGKILL_GRACE_MS = 1e3;
 var PID_TERMINATION_POLL_MS = 100;
 
-// src/debug-session/process-identity.ts
-import { execFile as execFile2 } from "child_process";
-import { readFile } from "fs/promises";
-import nodeProcess3 from "process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile2);
-function errorCode(error) {
-  if (typeof error !== "object" || error === null) {
-    return void 0;
-  }
-  const code = Reflect.get(error, "code");
-  return typeof code === "string" ? code : void 0;
-}
-function parseLinuxProcessStartTime(statLine) {
-  const commandEnd = statLine.lastIndexOf(")");
-  if (commandEnd < 0) {
-    return void 0;
-  }
-  const fieldsAfterCommand = statLine.slice(commandEnd + 1).trim().split(/\s+/);
-  const startTime = fieldsAfterCommand[19];
-  return startTime !== void 0 && /^\d+$/.test(startTime) ? startTime : void 0;
-}
-function throwIfAborted(signal) {
-  if (signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Process identity inspection was aborted.");
-  }
-}
-async function linuxProcessIdentity(pid, signal) {
-  try {
-    const statLine = await readFile(`/proc/${pid.toString()}/stat`, {
-      encoding: "utf8",
-      ...signal === void 0 ? {} : { signal }
-    });
-    const startTime = parseLinuxProcessStartTime(statLine);
-    return startTime === void 0 ? void 0 : `linux:${startTime}`;
-  } catch (error) {
-    throwIfAborted(signal);
-    if (errorCode(error) === "ENOENT") {
-      return void 0;
-    }
-    return void 0;
-  }
-}
-async function darwinProcessIdentity(pid, signal) {
-  try {
-    const { stdout } = await execFileAsync("ps", ["-p", pid.toString(), "-o", "lstart="], {
-      ...signal === void 0 ? {} : { signal },
-      timeout: 2e3
-    });
-    const startedAt = stdout.trim();
-    return startedAt.length === 0 ? void 0 : `darwin:${startedAt}`;
-  } catch {
-    throwIfAborted(signal);
-    return void 0;
-  }
-}
-async function readProcessIdentity(pid, signal) {
-  throwIfAborted(signal);
-  if (!Number.isSafeInteger(pid) || pid <= 0) {
-    return void 0;
-  }
-  if (nodeProcess3.platform === "linux") {
-    return await linuxProcessIdentity(pid, signal);
-  }
-  if (nodeProcess3.platform === "darwin") {
-    return await darwinProcessIdentity(pid, signal);
-  }
-  return void 0;
-}
-async function inspectProcessIdentity(pid, expected, signal) {
-  throwIfAborted(signal);
-  if (expected === void 0) {
-    return "match";
-  }
-  const current = await readProcessIdentity(pid, signal);
-  if (current === void 0) {
-    return "unavailable";
-  }
-  return current === expected ? "match" : "mismatch";
-}
-
 // src/lock.ts
 import { randomUUID } from "crypto";
 import { chmod, mkdir, open, readFile as readFile2, stat, unlink } from "fs/promises";
@@ -1438,18 +1688,7 @@ async function readLockOwner(lockPath) {
     throw error;
   }
 }
-async function isStaleLock(lockPath, staleMs) {
-  let modifiedAt2;
-  try {
-    modifiedAt2 = (await stat(lockPath)).mtimeMs;
-  } catch (error) {
-    if (errorCode2(error) === "ENOENT") {
-      return true;
-    }
-    throw error;
-  }
-  const owner = await readLockOwner(lockPath);
-  const ageMs = Date.now() - modifiedAt2;
+async function lockOwnerIsStale(owner, ageMs, staleMs) {
   if (owner?.hostname === hostname()) {
     if (!isProcessAlive(owner.pid)) {
       return true;
@@ -1470,20 +1709,54 @@ async function isStaleLock(lockPath, staleMs) {
   }
   return ageMs > staleMs * FOREIGN_HOST_STALE_MULTIPLIER;
 }
-async function reclaimAbandonedRecoveryLock(recoveryPath, staleMs) {
-  if (!await isStaleLock(recoveryPath, staleMs)) {
-    return;
+async function inspectLockStaleness(lockPath, staleMs) {
+  const owner = await readLockOwner(lockPath);
+  try {
+    const stats = await stat(lockPath);
+    return {
+      fingerprint: lockFingerprint(stats),
+      owner,
+      stale: await lockOwnerIsStale(owner, Date.now() - stats.mtimeMs, staleMs),
+      status: "present"
+    };
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      return { status: "missing" };
+    }
+    throw error;
   }
-  const owner = await readLockOwner(recoveryPath);
-  if (owner !== void 0) {
-    await removeOwnedLock(recoveryPath, owner.token);
-    return;
+}
+function lockFingerprint(stats) {
+  return [
+    stats.dev.toString(),
+    stats.ino.toString(),
+    stats.size.toString(),
+    stats.mtimeMs.toString()
+  ].join(":");
+}
+async function removeObservedLock(lockPath, observation) {
+  if (observation.owner !== void 0) {
+    return await removeOwnedLock(lockPath, observation.owner.token);
   }
-  await unlink(recoveryPath).catch((error) => {
-    if (errorCode2(error) !== "ENOENT") {
-      throw error;
+  try {
+    if (lockFingerprint(await stat(lockPath)) !== observation.fingerprint) {
+      return false;
     }
-  });
+    await unlink(lockPath);
+    return true;
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function reclaimAbandonedRecoveryLock(recoveryPath, staleMs) {
+  const observation = await inspectLockStaleness(recoveryPath, staleMs);
+  if (observation.status !== "present" || !observation.stale || observation.owner === void 0) {
+    return;
+  }
+  await removeOwnedLock(recoveryPath, observation.owner.token);
 }
 async function reclaimStaleLock(lockPath, staleMs) {
   const recoveryPath = `${lockPath}.recovery`;
@@ -1498,17 +1771,11 @@ async function reclaimStaleLock(lockPath, staleMs) {
     throw error;
   }
   try {
-    if (!await isStaleLock(lockPath, staleMs)) {
+    const observation = await inspectLockStaleness(lockPath, staleMs);
+    if (observation.status !== "present" || !observation.stale) {
       return false;
     }
-    try {
-      await unlink(lockPath);
-    } catch (error) {
-      if (errorCode2(error) !== "ENOENT") {
-        throw error;
-      }
-    }
-    return true;
+    return await removeObservedLock(lockPath, observation);
   } finally {
     await releaseFileLock(recoveryPath, recoveryLock);
   }
@@ -1516,12 +1783,13 @@ async function reclaimStaleLock(lockPath, staleMs) {
 async function removeOwnedLock(lockPath, token) {
   const owner = await readLockOwner(lockPath);
   if (owner?.token !== token) {
-    return;
+    return false;
   }
-  await unlink(lockPath).catch((error) => {
+  return await unlink(lockPath).then(() => true).catch((error) => {
     if (errorCode2(error) !== "ENOENT") {
       throw error;
     }
+    return false;
   });
 }
 async function createFileLock(lockPath) {
@@ -1794,16 +2062,24 @@ function decodeSession(value) {
     return void 0;
   }
 }
-function duplicateSessionIds(sessions) {
+function decodeSessions(rawSessions) {
   const seen = /* @__PURE__ */ new Set();
-  const duplicates = /* @__PURE__ */ new Set();
-  for (const session of sessions) {
+  const sessions = [];
+  const dropped = [];
+  for (const [index, raw] of rawSessions.entries()) {
+    const session = decodeSession(raw);
+    if (session === void 0) {
+      dropped.push(`session[${index.toString()}]: invalid entry`);
+      continue;
+    }
     if (seen.has(session.sessionId)) {
-      duplicates.add(session.sessionId);
+      dropped.push(`session[${index.toString()}]: duplicate sessionId ${session.sessionId}`);
+      continue;
     }
     seen.add(session.sessionId);
+    sessions.push(session);
   }
-  return duplicates;
+  return { dropped, sessions };
 }
 function decodeStateFileDetailed(value) {
   if (typeof value !== "object" || value === null) {
@@ -1816,36 +2092,46 @@ function decodeStateFileDetailed(value) {
   if (!Array.isArray(rawSessions)) {
     return { kind: "invalid-file", reason: "sessions is not an array" };
   }
-  const decoded = rawSessions.map((raw) => decodeSession(raw));
-  const valid = decoded.filter((session) => session !== void 0);
-  const duplicates = duplicateSessionIds(valid);
-  const sessions = valid.filter((session) => !duplicates.has(session.sessionId));
-  const dropped = decoded.flatMap((session, index) => {
-    if (session === void 0) {
-      return [`session[${index.toString()}]: invalid entry`];
-    }
-    return duplicates.has(session.sessionId) ? [`session[${index.toString()}]: duplicate sessionId ${session.sessionId}`] : [];
-  });
+  const decoded = decodeSessions(rawSessions);
   return {
     kind: "decoded",
-    state: { version: "2", sessions },
-    dropped
+    state: { version: "2", sessions: decoded.sessions },
+    dropped: decoded.dropped
   };
 }
 
 // src/session-state/health.ts
 import { hostname as getHostname } from "os";
-import nodeProcess4 from "process";
+import nodeProcess5 from "process";
+
+// src/debug-session/session-process.ts
+function startupAgeLimit(session) {
+  return (session.startupTimeoutMs ?? MAX_STARTUP_TIMEOUT_MS) + STARTUP_STALE_SLACK_MS;
+}
+function startupExpired(session) {
+  const startedAt = Date.parse(session.startedAt);
+  return Number.isNaN(startedAt) || Date.now() - startedAt > startupAgeLimit(session);
+}
+async function inspectRecordedProcess(pid, identity, isAlive, signal) {
+  if (signal?.aborted) {
+    throw new CfDebuggerError("ABORTED", "Session health inspection was aborted.");
+  }
+  if (!isAlive(pid)) {
+    return "dead";
+  }
+  return await inspectProcessIdentity(pid, identity, signal);
+}
 
 // src/network/ports.ts
 import { execFile as execFile3 } from "child_process";
 import { readdir, readFile as readFile3, readlink } from "fs/promises";
 import { get as httpGet } from "http";
-import { createConnection, createServer } from "net";
+import { createServer, Socket } from "net";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile3);
 var PROBE_INTERVAL_MS = 250;
-var INSPECTOR_ATTEMPT_TIMEOUT_MS = 2500;
+var INITIAL_INSPECTOR_ATTEMPT_TIMEOUT_MS = 2500;
+var MAX_INSPECTOR_ATTEMPT_TIMEOUT_MS = 1e4;
 var MAX_INSPECTOR_RESPONSE_BYTES = 64 * 1024;
 var OWNER_COMMAND_TIMEOUT_MS = 5e3;
 function sortedUniquePids(pids) {
@@ -2101,22 +2387,32 @@ async function isPortFree(port, signal) {
 }
 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", () => {
+    const socket = new Socket();
+    let settled = false;
+    const finish = (listening) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
       socket.destroy();
-      resolve(true);
+      resolve(listening);
+    };
+    socket.once("connect", () => {
+      finish(true);
     });
     socket.once("error", () => {
-      socket.destroy();
-      resolve(false);
+      finish(false);
     });
     socket.once("timeout", () => {
-      socket.destroy();
-      resolve(false);
+      finish(false);
     });
+    socket.setTimeout(positiveTimeout(timeoutMs));
+    socket.connect({ port, host: "127.0.0.1" });
   });
 }
+function positiveTimeout(timeoutMs) {
+  return Number.isFinite(timeoutMs) ? Math.max(1, Math.floor(timeoutMs)) : 1;
+}
 function throwIfAborted2(signal) {
   if (signal?.aborted) {
     throw new CfDebuggerError("ABORTED", "Operation aborted by caller");
@@ -2144,7 +2440,7 @@ async function probeTunnelReady(port, timeoutMs, signal) {
   throwIfAborted2(signal);
   while (Date.now() < deadline) {
     const remainingMs = deadline - Date.now();
-    if (await isPortListening(port, Math.min(200, remainingMs))) {
+    if (await isPortListening(port, positiveTimeout(Math.min(200, remainingMs)))) {
       return true;
     }
     const waitMs = Math.min(PROBE_INTERVAL_MS, Math.max(0, deadline - Date.now()));
@@ -2213,21 +2509,28 @@ function readInspectorResponse(response, finish) {
     finish(false);
   });
 }
+function finishInspectorAttempt(state, ready, resolve) {
+  if (state.settled) {
+    return;
+  }
+  state.settled = true;
+  clearTimeout(state.timer);
+  state.removeAbortListener?.();
+  resolve(ready);
+}
 function probeInspectorAttempt(port, timeoutMs, signal) {
   throwIfAborted2(signal);
   return new Promise((resolve, reject) => {
     const state = { settled: false };
     const finish = (ready) => {
-      if (!state.settled) {
-        state.settled = true;
-        clearTimeout(state.timer);
-        state.removeAbortListener?.();
-        resolve(ready);
-      }
+      finishInspectorAttempt(state, ready, resolve);
     };
-    const request = httpGet({ host: "127.0.0.1", port, path: "/json/list" }, (response) => {
-      readInspectorResponse(response, finish);
-    });
+    const request = httpGet(
+      { agent: false, host: "127.0.0.1", port, path: "/json/list" },
+      (response) => {
+        readInspectorResponse(response, finish);
+      }
+    );
     const onAbort = () => {
       request.destroy();
       if (!state.settled) {
@@ -2248,7 +2551,7 @@ function probeInspectorAttempt(port, timeoutMs, signal) {
     state.timer = setTimeout(() => {
       request.destroy();
       finish(false);
-    }, timeoutMs);
+    }, positiveTimeout(timeoutMs));
     request.once("error", () => {
       if (signal?.aborted) {
         onAbort();
@@ -2258,18 +2561,25 @@ function probeInspectorAttempt(port, timeoutMs, signal) {
     });
   });
 }
+function inspectorAttemptTimeout(attempt, remainingMs) {
+  const growingCap = Math.min(
+    MAX_INSPECTOR_ATTEMPT_TIMEOUT_MS,
+    INITIAL_INSPECTOR_ATTEMPT_TIMEOUT_MS * 2 ** attempt
+  );
+  const retryShare = Math.ceil(remainingMs / 2);
+  return positiveTimeout(Math.min(growingCap, retryShare, remainingMs));
+}
 async function probeInspectorReady(port, timeoutMs, signal) {
   const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
   throwIfAborted2(signal);
   while (Date.now() < deadline) {
     const remainingMs = deadline - Date.now();
-    const attemptTimeoutMs = Math.max(
-      1,
-      Math.min(INSPECTOR_ATTEMPT_TIMEOUT_MS, remainingMs)
-    );
+    const attemptTimeoutMs = inspectorAttemptTimeout(attempt, remainingMs);
     if (await probeInspectorAttempt(port, attemptTimeoutMs, signal)) {
       return { status: "ready" };
     }
+    attempt += 1;
     const waitMs = Math.min(PROBE_INTERVAL_MS, Math.max(0, deadline - Date.now()));
     if (waitMs > 0) {
       await waitForNextProbe(waitMs, signal);
@@ -2289,34 +2599,18 @@ function errorCode4(error) {
 }
 function isPidAlive(pid) {
   try {
-    nodeProcess4.kill(pid, 0);
+    nodeProcess5.kill(pid, 0);
     return true;
   } catch (error) {
     return errorCode4(error) !== "ESRCH";
   }
 }
 function isProcessGroupAlive(pid) {
-  return nodeProcess4.platform !== "win32" && isPidAlive(-pid);
+  return nodeProcess5.platform !== "win32" && isPidAlive(-pid);
 }
 function isPidOrGroupAlive(pid) {
   return isPidAlive(pid) || isProcessGroupAlive(pid);
 }
-function startupAgeLimit(session) {
-  return (session.startupTimeoutMs ?? MAX_STARTUP_TIMEOUT_MS) + STARTUP_STALE_SLACK_MS;
-}
-function startupExpired(session) {
-  const startedAt = Date.parse(session.startedAt);
-  return Number.isNaN(startedAt) || Date.now() - startedAt > startupAgeLimit(session);
-}
-async function inspectRecordedProcess(pid, identity, signal) {
-  if (signal?.aborted) {
-    throw new CfDebuggerError("ABORTED", "Session health inspection was aborted.");
-  }
-  if (!isPidAlive(pid)) {
-    return "dead";
-  }
-  return await inspectProcessIdentity(pid, identity, signal);
-}
 async function readySessionHealth(session, signal) {
   const tunnelPid = session.tunnelPid;
   if (tunnelPid === void 0) {
@@ -2325,6 +2619,7 @@ async function readySessionHealth(session, signal) {
   const processVerdict = await inspectRecordedProcess(
     tunnelPid,
     session.tunnelProcessIdentity,
+    isPidAlive,
     signal
   );
   if (processVerdict === "dead" && isProcessGroupAlive(tunnelPid)) {
@@ -2362,6 +2657,7 @@ async function startingSessionHealth(session, signal) {
   const processVerdict = await inspectRecordedProcess(
     controllerPid,
     session.controllerProcessIdentity,
+    isPidAlive,
     signal
   );
   if (processVerdict === "match") {
@@ -2381,19 +2677,16 @@ async function inspectSessionHealth(session, host = getHostname(), signal) {
   }
   return session.status === "ready" ? await readySessionHealth(session, signal) : await startingSessionHealth(session, signal);
 }
-async function filterStaleSessions(sessions, signal) {
-  const host = getHostname();
-  const verdicts = await Promise.all(
-    sessions.map(async (session) => [
-      session,
-      await inspectSessionHealth(session, host, signal)
-    ])
-  );
-  return verdicts.filter(([, verdict]) => verdict.status !== "stale").map(([session]) => session);
-}
 
 // src/session-state/stop-intent.ts
-import { access, chmod as chmod2, mkdir as mkdir2, unlink as unlink2, writeFile } from "fs/promises";
+import {
+  access,
+  chmod as chmod2,
+  mkdir as mkdir2,
+  readFile as readFile4,
+  unlink as unlink2,
+  writeFile
+} from "fs/promises";
 function errorCode5(error) {
   if (typeof error !== "object" || error === null) {
     return void 0;
@@ -2428,6 +2721,29 @@ async function hasSessionStopIntent(sessionId) {
     throw error;
   }
 }
+async function inspectSessionStateStopIntent(sessionId) {
+  let raw;
+  try {
+    raw = await readFile4(stateFilePath(), "utf8");
+  } catch (error) {
+    return errorCode5(error) === "ENOENT" ? "missing" : "unavailable";
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "unavailable";
+  }
+  const decoded = decodeStateFileDetailed(parsed);
+  if (decoded.kind === "invalid-file") {
+    return "unavailable";
+  }
+  const session = decoded.state.sessions.find((candidate) => candidate.sessionId === sessionId);
+  if (session === void 0) {
+    return decoded.dropped.length > 0 ? "unavailable" : "missing";
+  }
+  return session.stopRequestedAt !== void 0 || session.status === "stopping" ? "requested" : "active";
+}
 async function clearSessionStopIntent(sessionId) {
   await unlink2(sessionStopIntentPath(sessionId)).catch((error) => {
     if (errorCode5(error) !== "ENOENT") {
@@ -2449,7 +2765,7 @@ function errorCode6(error) {
 async function readFileIfPresent(path) {
   try {
     await chmod3(path, 384);
-    return await readFile4(path, "utf8");
+    return await readFile5(path, "utf8");
   } catch (error) {
     if (errorCode6(error) === "ENOENT") {
       return void 0;
@@ -2490,7 +2806,7 @@ async function preserveCorruptState(path, reason) {
   const backup = corruptBackupPath(path);
   await rename(path, backup);
   await chmod3(backup, 384);
-  nodeProcess5.stderr.write(
+  nodeProcess6.stderr.write(
     `[cf-debugger] warning: preserved invalid state at ${backup} (${reason}).
 `
   );
@@ -2521,7 +2837,7 @@ async function readStateRaw() {
   if (decoded.dropped.length > 0) {
     await preserveCorruptState(path, decoded.dropped.join("; "));
     await writeJsonFileAtomic(path, decoded.state);
-    nodeProcess5.stderr.write(
+    nodeProcess6.stderr.write(
       `[cf-debugger] warning: dropped ${decoded.dropped.length.toString()} invalid state entr${decoded.dropped.length === 1 ? "y" : "ies"}; valid sessions were retained.
 `
     );
@@ -2531,22 +2847,62 @@ async function readStateRaw() {
 async function writeState(state) {
   await writeJsonFileAtomic(stateFilePath(), state);
 }
-async function readAndPruneLocked(signal) {
-  const raw = await readStateRaw();
+function samePersistedSession(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+async function inspectPruneCandidates(raw, signal) {
   const host = getHostname2();
-  const remote = raw.sessions.filter((session) => session.hostname !== host);
   const local = raw.sessions.filter((session) => session.hostname === host);
-  const sessions = await filterStaleSessions(local, signal);
-  const activeIds = new Set(sessions.map((session) => session.sessionId));
-  const removed = local.filter((session) => !activeIds.has(session.sessionId));
-  const persisted = { version: "2", sessions: [...remote, ...sessions] };
+  const verdicts = await Promise.all(local.map(async (session) => ({
+    session,
+    verdict: await inspectSessionHealth(session, host, signal)
+  })));
+  return {
+    snapshotById: new Map(local.map((session) => [session.sessionId, session])),
+    staleIds: new Set(
+      verdicts.filter(({ verdict }) => verdict.status === "stale").map(({ session }) => session.sessionId)
+    )
+  };
+}
+async function persistPruneInspection(inspection, signal) {
+  const raw = await readStateRaw();
+  const host = getHostname2();
+  const removed = [];
+  const sessions = [];
+  for (const session of raw.sessions.filter((entry) => entry.hostname === host)) {
+    const snapshot = inspection.snapshotById.get(session.sessionId);
+    if (snapshot === void 0 || !inspection.staleIds.has(session.sessionId) || !samePersistedSession(snapshot, session)) {
+      sessions.push(session);
+      continue;
+    }
+    const verdict = await inspectSessionHealth(session, host, signal);
+    if (verdict.status === "stale") {
+      removed.push(session);
+    } else {
+      sessions.push(session);
+    }
+  }
   if (removed.length > 0) {
-    await writeState(persisted);
+    const remote = raw.sessions.filter((session) => session.hostname !== host);
+    await writeState({ version: "2", sessions: [...remote, ...sessions] });
   }
-  return { sessions, removed, persisted };
+  return { sessions, removed };
+}
+async function inspectAndPrune(options) {
+  const snapshot = await withFileLock(
+    stateLockPath(),
+    readStateRaw,
+    options
+  );
+  const inspection = await inspectPruneCandidates(snapshot, options?.signal);
+  return await withFileLock(
+    stateLockPath(),
+    async () => await persistPruneInspection(inspection, options?.signal),
+    options
+  );
 }
 async function readActiveSessions() {
-  const result = await withFileLock(stateLockPath(), readAndPruneLocked);
+  const result = await inspectAndPrune();
   return result.sessions;
 }
 async function readSessionSnapshot(options) {
@@ -2555,12 +2911,7 @@ async function readSessionSnapshot(options) {
   }, options);
 }
 async function readAndPruneActiveSessions(options) {
-  const result = await withFileLock(
-    stateLockPath(),
-    async () => await readAndPruneLocked(options?.signal),
-    options
-  );
-  return { sessions: result.sessions, removed: result.removed };
+  return await inspectAndPrune(options);
 }
 function sessionKeyString(key) {
   const base = `${key.region}:${key.org}:${key.space}:${key.app}`;
@@ -2593,34 +2944,41 @@ function matchesRegistrationTarget(session, input, target) {
     apiEndpoint: input.apiEndpoint
   });
 }
-async function pickPort(preferred, reserved, probe, basePort, maxPort) {
+function portCandidates(preferred, range, scanOffset) {
   const candidates = preferred === void 0 ? [] : [preferred];
-  for (let port = basePort; port <= maxPort; port += 1) {
+  const size = range.maxPort - range.basePort + 1;
+  for (let index = 0; index < size; index += 1) {
+    const port = range.basePort + (scanOffset + index) % size;
     if (port !== preferred) {
       candidates.push(port);
     }
   }
-  for (const port of candidates) {
+  return candidates;
+}
+async function pickPort(preferred, reserved, probe, range, scanOffset) {
+  for (const port of portCandidates(preferred, range, scanOffset)) {
     if (!reserved.has(port) && await probe(port)) {
       return port;
     }
   }
   throw new CfDebuggerError(
     "PORT_UNAVAILABLE",
-    `No free local port available in range ${basePort.toString()}\u2013${maxPort.toString()}`
+    `No free local port available in range ${range.basePort.toString()}\u2013${range.maxPort.toString()}`
   );
 }
-async function selectRegistrationCandidate(input, target, excluded) {
+async function selectRegistrationCandidate(input, target, excluded, range, scanOffset) {
+  await readAndPruneActiveSessions(input.stateAccess);
   return await withFileLock(stateLockPath(), async () => {
-    const current = await readAndPruneLocked(input.stateAccess?.signal);
-    const existing = current.sessions.find(
+    const raw = await readStateRaw();
+    const local = raw.sessions.filter((session) => session.hostname === getHostname2());
+    const existing = local.find(
       (session) => matchesRegistrationTarget(session, input, target)
     );
     if (existing !== void 0) {
       return { existing };
     }
     const reserved = /* @__PURE__ */ new Set([
-      ...current.sessions.map((session) => session.localPort),
+      ...local.map((session) => session.localPort),
       ...excluded
     ]);
     return {
@@ -2628,20 +2986,58 @@ async function selectRegistrationCandidate(input, target, excluded) {
         input.preferredPort,
         reserved,
         () => Promise.resolve(true),
-        input.basePort ?? DEFAULT_BASE_PORT,
-        input.maxPort ?? DEFAULT_MAX_PORT
+        range,
+        scanOffset
       )
     };
   }, input.stateAccess);
 }
+function validateTcpPort(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > 65535) {
+    throw new CfDebuggerError("UNSAFE_INPUT", `${label} must be from 1 to 65535.`);
+  }
+}
+function validatePortRange(input) {
+  const basePort = input.basePort ?? DEFAULT_BASE_PORT;
+  const maxPort = input.maxPort ?? DEFAULT_MAX_PORT;
+  validateTcpPort(basePort, "Local port range start");
+  validateTcpPort(maxPort, "Local port range end");
+  if (basePort > maxPort) {
+    throw new CfDebuggerError(
+      "UNSAFE_INPUT",
+      "Local port range start must not exceed its end."
+    );
+  }
+  if (input.preferredPort !== void 0) {
+    validateTcpPort(input.preferredPort, "Preferred local port");
+  }
+  return { basePort, maxPort };
+}
 function validateSessionInput(input) {
+  validateCfCliOperand(input.region, "Region");
+  validateCfCliOperand(input.org, "Cloud Foundry org");
+  validateCfCliOperand(input.space, "Cloud Foundry space");
+  validateCfCliOperand(input.app, "Cloud Foundry app");
+  validateCfCliOperand(input.apiEndpoint, "Cloud Foundry API endpoint");
   const remotePort = input.remotePort ?? DEFAULT_NODE_INSPECTOR_PORT;
-  if (!Number.isSafeInteger(remotePort) || remotePort <= 0 || remotePort > 65535) {
-    throw new CfDebuggerError("UNSAFE_INPUT", "Remote inspector port must be from 1 to 65535.");
-  }
+  validateTcpPort(remotePort, "Remote inspector port");
   if (input.startupTimeoutMs !== void 0 && (!Number.isSafeInteger(input.startupTimeoutMs) || input.startupTimeoutMs <= 0 || input.startupTimeoutMs > MAX_STARTUP_TIMEOUT_MS)) {
     throw new CfDebuggerError("UNSAFE_INPUT", "Persisted startup timeout is outside the supported range.");
   }
+  return validatePortRange(input);
+}
+function registrationScanOffset(input, target, range) {
+  const identity = JSON.stringify([
+    input.apiEndpoint,
+    input.region,
+    input.org,
+    input.space,
+    input.app,
+    target.process,
+    target.instance
+  ]);
+  const hash = createHash("sha256").update(identity).digest().readUInt32BE(0);
+  return hash % (range.maxPort - range.basePort + 1);
 }
 function createRegisteredSession(input, target, localPort, controllerProcessIdentity) {
   const sessionId = (input.sessionIdFactory ?? randomUUID2)();
@@ -2654,8 +3050,8 @@ function createRegisteredSession(input, target, localPort, controllerProcessIden
   }
   return {
     sessionId,
-    pid: nodeProcess5.pid,
-    controllerPid: nodeProcess5.pid,
+    pid: nodeProcess6.pid,
+    controllerPid: nodeProcess6.pid,
     ...controllerProcessIdentity === void 0 ? {} : { controllerProcessIdentity },
     hostname: getHostname2(),
     region: input.region,
@@ -2675,37 +3071,46 @@ function createRegisteredSession(input, target, localPort, controllerProcessIden
   };
 }
 async function persistRegistration(input, target, candidate, controllerProcessIdentity) {
+  await readAndPruneActiveSessions(input.stateAccess);
   return await withFileLock(stateLockPath(), async () => {
-    const current = await readAndPruneLocked(input.stateAccess?.signal);
-    const existing = current.sessions.find(
+    const raw = await readStateRaw();
+    const local = raw.sessions.filter((session2) => session2.hostname === getHostname2());
+    const existing = local.find(
       (session2) => matchesRegistrationTarget(session2, input, target)
     );
     if (existing !== void 0) {
       return { session: existing, existing };
     }
-    const reserved = current.sessions.some((session2) => session2.localPort === candidate);
+    const reserved = local.some((session2) => session2.localPort === candidate);
     if (reserved || !await input.portProbe(candidate)) {
       return void 0;
     }
     const session = createRegisteredSession(input, target, candidate, controllerProcessIdentity);
     await writeState({
       version: "2",
-      sessions: [...current.persisted.sessions, session]
+      sessions: [...raw.sessions, session]
     });
     return { session };
   }, input.stateAccess);
 }
 async function registerNewSession(input) {
-  validateSessionInput(input);
+  const range = validateSessionInput(input);
   const target = resolveNodeTarget(input);
+  const scanOffset = registrationScanOffset(input, target, range);
   const controllerIdentity = await readProcessIdentity(
-    nodeProcess5.pid,
+    nodeProcess6.pid,
     input.stateAccess?.signal
   );
   const excluded = /* @__PURE__ */ new Set();
-  const maximumAttempts = (input.maxPort ?? DEFAULT_MAX_PORT) - (input.basePort ?? DEFAULT_BASE_PORT) + 2;
+  const maximumAttempts = range.maxPort - range.basePort + 2;
   for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
-    const selection = await selectRegistrationCandidate(input, target, excluded);
+    const selection = await selectRegistrationCandidate(
+      input,
+      target,
+      excluded,
+      range,
+      scanOffset
+    );
     if (selection.existing !== void 0) {
       return { session: selection.existing, existing: selection.existing };
     }
@@ -2819,9 +3224,6 @@ async function requestSessionStop(sessionId) {
     if (target === void 0) {
       return void 0;
     }
-    if (target.status === "ready") {
-      return { session: target, previousStatus: target.status };
-    }
     await writeSessionStopIntent(sessionId);
     if (target.stopRequestedAt !== void 0) {
       return { session: target, previousStatus: target.status };
@@ -2875,51 +3277,59 @@ function cliErrorExitCode(error) {
   }
   return hasCleanupFailure(error) ? CLEANUP_FAILURE_EXIT_CODE : 1;
 }
+function stopAllExitCode(errors) {
+  if (errors.length === 0) {
+    return void 0;
+  }
+  return errors.some((error) => hasTunnelTerminationFailure(error)) ? CLEANUP_FAILURE_EXIT_CODE : 1;
+}
 
 // src/debug-session/lifecycle.ts
 import { constants as osConstants } from "os";
 
 // src/debug-session/processes.ts
 import process3 from "process";
-async function terminatePidOrGroup(pid, timeoutMs = CHILD_SIGTERM_GRACE_MS, pinnedTarget, verifyBeforeSignal) {
-  const targetKind = pinnedTarget ?? (isProcessGroupAlive(pid) ? "group" : "pid");
-  const targetAlive = () => targetKind === "group" ? isProcessGroupAlive(pid) : isPidAlive(pid);
-  if (!targetAlive()) {
-    return "terminated";
-  }
-  if (verifyBeforeSignal !== void 0 && !await verifyBeforeSignal("SIGTERM")) {
-    return "ownership-lost";
-  }
+function terminationTargetAlive(pid, targetKind) {
+  return targetKind === "group" ? isProcessGroupAlive(pid) : isPidAlive(pid);
+}
+function signalTerminationTarget(pid, targetKind, signal) {
   try {
-    process3.kill(targetKind === "group" ? -pid : pid, "SIGTERM");
+    process3.kill(targetKind === "group" ? -pid : pid, signal);
   } catch {
   }
+}
+async function waitForTargetExit(pid, targetKind, timeoutMs) {
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
-    if (!targetAlive()) {
-      return "terminated";
+    if (!terminationTargetAlive(pid, targetKind)) {
+      return true;
     }
     await new Promise((resolve) => {
       setTimeout(resolve, PID_TERMINATION_POLL_MS);
     });
   }
-  if (verifyBeforeSignal !== void 0 && !await verifyBeforeSignal("SIGKILL")) {
+  return !terminationTargetAlive(pid, targetKind);
+}
+async function signalIsAuthorized(verifier, signal) {
+  return verifier === void 0 || await verifier(signal);
+}
+async function terminatePidOrGroup(pid, timeoutMs = CHILD_SIGTERM_GRACE_MS, pinnedTarget, verifyBeforeSignal) {
+  const targetKind = pinnedTarget ?? (isProcessGroupAlive(pid) ? "group" : "pid");
+  if (!terminationTargetAlive(pid, targetKind)) {
+    return "terminated";
+  }
+  if (!await signalIsAuthorized(verifyBeforeSignal, "SIGTERM")) {
     return "ownership-lost";
   }
-  try {
-    process3.kill(targetKind === "group" ? -pid : pid, "SIGKILL");
-  } catch {
+  signalTerminationTarget(pid, targetKind, "SIGTERM");
+  if (await waitForTargetExit(pid, targetKind, timeoutMs)) {
+    return "terminated";
   }
-  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);
-    });
+  if (!await signalIsAuthorized(verifyBeforeSignal, "SIGKILL")) {
+    return "ownership-lost";
   }
-  return targetAlive() ? "still-alive" : "terminated";
+  signalTerminationTarget(pid, targetKind, "SIGKILL");
+  return await waitForTargetExit(pid, targetKind, CHILD_SIGKILL_GRACE_MS) ? "terminated" : "still-alive";
 }
 async function killProcessGroupOrProc(child, verifyBeforeSignal, timeoutMs = CHILD_SIGTERM_GRACE_MS) {
   if (child.pid === void 0) {
@@ -2938,7 +3348,39 @@ async function killProcessGroupOrProc(child, verifyBeforeSignal, timeoutMs = CHI
 }
 
 // src/debug-session/session-home.ts
-import { rm } from "fs/promises";
+import { lstat, rm } from "fs/promises";
+import { dirname as dirname3 } from "path";
+function errorCode7(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 inspectSessionHomesRoot(root) {
+  try {
+    const stats = await lstat(root);
+    if (stats.isSymbolicLink()) {
+      return {
+        status: "unsafe",
+        reason: `Debugger CF homes root ${root} is a symbolic link; refusing to traverse it.`
+      };
+    }
+    return stats.isDirectory() ? { status: "safe" } : {
+      status: "unsafe",
+      reason: `Debugger CF homes root ${root} is not a directory; refusing to traverse it.`
+    };
+  } catch (error) {
+    if (errorCode7(error) === "ENOENT") {
+      return { status: "absent" };
+    }
+    const code = errorCode7(error) ?? "unknown error";
+    return {
+      status: "unsafe",
+      reason: `Debugger CF homes root ${root} could not be inspected (${code}); refusing to traverse it.`
+    };
+  }
+}
 async function removeOwnedSessionCfHome(sessionId, candidate) {
   if (!isOwnedSessionCfHomeDir(sessionId, candidate)) {
     throw new CfDebuggerError(
@@ -2946,6 +3388,10 @@ async function removeOwnedSessionCfHome(sessionId, candidate) {
       `Refusing to remove unowned debugger CF home for session ${sessionId}.`
     );
   }
+  const rootInspection = await inspectSessionHomesRoot(dirname3(candidate));
+  if (rootInspection.status === "unsafe") {
+    throw new CfDebuggerError("UNSAFE_INPUT", rootInspection.reason);
+  }
   await rm(candidate, { recursive: true, force: true });
 }
 async function tryRemoveOwnedSessionCfHome(sessionId, candidate) {
@@ -2960,13 +3406,30 @@ async function tryRemoveOwnedSessionCfHome(sessionId, candidate) {
   }
 }
 
+// src/debug-session/session-cleanup.ts
+async function forgetSessionThenCleanupHome(session) {
+  const removed = await removeSession(session.sessionId);
+  if (!isOwnedSessionCfHomeDir(session.sessionId, session.cfHomeDir)) {
+    return { homeStatus: "unowned", removed };
+  }
+  const homeRemoved = await tryRemoveOwnedSessionCfHome(
+    session.sessionId,
+    session.cfHomeDir
+  );
+  return {
+    homeStatus: homeRemoved ? "removed" : "retained",
+    removed
+  };
+}
+
 // src/debug-session/lifecycle.ts
 var handleLifecycles = /* @__PURE__ */ new WeakMap();
-function childIsOpen(child) {
+function childIsOpen2(child) {
   return child.exitCode === null && child.signalCode === null;
 }
 function signalExitCode(signal) {
-  return 128 + osConstants.signals[signal];
+  const signum = osConstants.signals[signal];
+  return typeof signum === "number" && Number.isFinite(signum) ? 128 + signum : 1;
 }
 function unexpectedExitCode(code, signal) {
   if (signal !== null) {
@@ -2980,6 +3443,8 @@ function emitSafely(emit, status, message) {
   } catch {
   }
 }
+function ignoreCleanupFailure() {
+}
 async function runCleanupActions(actions, aggregateMessage) {
   const errors = [];
   for (const action of actions) {
@@ -2997,10 +3462,10 @@ async function runCleanupActions(actions, aggregateMessage) {
   }
 }
 async function handleTunnelClose(sessionId, code, signal, child, resolveExit, isFinalizing, hasFailed, markFailed, emit) {
-  const stopRequested = await hasSessionStopIntent(sessionId);
+  const stopRequested = isFinalizing() ? false : await hasExpectedStopSignal(sessionId);
   const expected = isFinalizing() || stopRequested;
   if (stopRequested) {
-    await clearSessionStopIntent(sessionId);
+    await clearSessionStopIntent(sessionId).catch(ignoreCleanupFailure);
   }
   if (!expected && !hasFailed()) {
     const detail = signal === null ? code === null ? "no exit status" : `exit code ${code.toString()}` : `signal ${signal}`;
@@ -3015,6 +3480,19 @@ async function handleTunnelClose(sessionId, code, signal, child, resolveExit, is
   }
   resolveExit(expected && !hasFailed() ? 0 : unexpectedExitCode(code, signal));
 }
+async function hasExpectedStopSignal(sessionId) {
+  let sidecarRequested = false;
+  try {
+    sidecarRequested = await hasSessionStopIntent(sessionId);
+  } catch {
+  }
+  try {
+    const verdict = await inspectSessionStateStopIntent(sessionId);
+    return verdict === "requested" || verdict === "missing" && sidecarRequested;
+  } catch {
+    return false;
+  }
+}
 function attachTunnelEvents(sessionId, child, resolveExit, isFinalizing, hasFailed, markFailed, emit) {
   child.once("close", (code, signal) => {
     void handleTunnelClose(
@@ -3057,87 +3535,126 @@ async function expectedTunnelStillOwned(session, child) {
   return ownership.status === "unverified" ? "unverified" : ownership.status === "owned";
 }
 async function cleanupFinishedSession(session) {
-  await removeOwnedSessionCfHome(session.sessionId, session.cfHomeDir);
-  await removeSession(session.sessionId);
-  await clearSessionStopIntent(session.sessionId);
+  const cleanup = await forgetSessionThenCleanupHome(session);
+  await clearSessionStopIntent(session.sessionId).catch(ignoreCleanupFailure);
+  if (cleanup.homeStatus !== "removed") {
+    throw new CfDebuggerError(
+      "CF_HOME_CLEANUP_FAILED",
+      cleanup.homeStatus === "retained" ? `Session state was removed, but owned CF home ${session.cfHomeDir} could not be deleted. It may contain a live CF refresh token; remove it manually or run \`cf-debugger doctor --cleanup\`.` : `Session state was removed, but unowned CF home ${session.cfHomeDir} was not deleted.`
+    );
+  }
 }
-function createTunnelLifecycle(session, emit) {
-  let child;
-  let childIdentity;
-  let childFailed = false;
-  let tunnelError;
-  let finalizing = false;
+function initializeTunnelLifecycle() {
   let exitResolve = (_code) => {
     throw new Error("Tunnel exit resolver was used before initialization.");
   };
   const exitPromise = new Promise((resolve) => {
     exitResolve = resolve;
   });
-  const observeChild = (tunnelChild) => {
-    child = tunnelChild;
-    childIdentity = tunnelChild.pid === void 0 ? void 0 : readProcessIdentity(tunnelChild.pid);
-    attachTunnelEvents(
-      session.sessionId,
-      tunnelChild,
-      exitResolve,
-      () => finalizing,
-      () => childFailed,
-      (error) => {
-        if (!childFailed) {
-          childFailed = true;
-          tunnelError = error;
-        }
-      },
-      emit
-    );
-  };
-  const verifyBeforeSignal = async (signal) => {
-    const tunnelChild = child;
-    const childPid = tunnelChild?.pid;
-    if (tunnelChild === void 0 || childPid === void 0 || !childIsOpen(tunnelChild)) {
-      return false;
-    }
-    const expectedIdentity = await childIdentity;
-    if (expectedIdentity !== void 0) {
-      return await inspectProcessIdentity(childPid, expectedIdentity) === "match" && childIsOpen(tunnelChild);
-    }
-    if (signal === "SIGKILL") {
-      return await expectedTunnelStillOwned(session, tunnelChild) === true;
+  return {
+    exitPromise,
+    state: {
+      child: void 0,
+      childIdentity: void 0,
+      childFailed: false,
+      tunnelError: void 0,
+      finalizing: false,
+      exitResolve
     }
-    return true;
   };
-  const finalize = async (emitStopped) => {
-    finalizing = true;
-    const termination = child === void 0 ? "terminated" : await killProcessGroupOrProc(child, verifyBeforeSignal);
-    const stillOwned = await expectedTunnelStillOwned(session, child);
-    if (termination !== "terminated" || stillOwned === true || stillOwned === "unverified") {
-      const stderr = child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(child));
-      throw new CfDebuggerError(
-        "TUNNEL_TERMINATION_FAILED",
-        `Tunnel for session ${session.sessionId} did not terminate cleanly; state and CF home were retained.`,
-        stderr
-      );
-    }
-    await cleanupFinishedSession(session);
-    if (emitStopped) {
-      emitSafely(emit, "stopped");
-    }
+}
+function recordTunnelFailure(state, error) {
+  if (!state.childFailed) {
+    state.childFailed = true;
+    state.tunnelError = error;
+  }
+}
+function observeTunnelChild(state, sessionId, tunnelChild, emit) {
+  state.child = tunnelChild;
+  state.childIdentity = tunnelChild.pid === void 0 ? void 0 : readProcessIdentity(tunnelChild.pid);
+  attachTunnelEvents(
+    sessionId,
+    tunnelChild,
+    state.exitResolve,
+    () => state.finalizing,
+    () => state.childFailed,
+    (error) => {
+      recordTunnelFailure(state, error);
+    },
+    emit
+  );
+}
+async function verifyTunnelBeforeSignal(state, session, signal) {
+  const tunnelChild = state.child;
+  const childPid = tunnelChild?.pid;
+  if (tunnelChild === void 0 || childPid === void 0 || !childIsOpen2(tunnelChild)) {
+    return false;
+  }
+  const expectedIdentity = await state.childIdentity;
+  if (expectedIdentity !== void 0) {
+    return await inspectProcessIdentity(childPid, expectedIdentity) === "match" && childIsOpen2(tunnelChild);
+  }
+  if (signal === "SIGKILL") {
+    return await expectedTunnelStillOwned(session, tunnelChild) === true;
+  }
+  return true;
+}
+function tunnelTerminationError(session, child) {
+  const stderr = child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(child));
+  return new CfDebuggerError(
+    "TUNNEL_TERMINATION_FAILED",
+    `Tunnel for session ${session.sessionId} did not terminate cleanly; state and CF home were retained.`,
+    stderr
+  );
+}
+async function finalizeTunnelLifecycle(state, session, emit, emitStopped) {
+  state.finalizing = true;
+  const verify = async (signal) => {
+    return await verifyTunnelBeforeSignal(state, session, signal);
   };
+  const termination = state.child === void 0 ? "terminated" : await killProcessGroupOrProc(state.child, verify);
+  const stillOwned = await expectedTunnelStillOwned(session, state.child);
+  if (termination !== "terminated" || stillOwned === true) {
+    throw tunnelTerminationError(session, state.child);
+  }
+  if (stillOwned === "unverified" && emitStopped) {
+    emitSafely(
+      emit,
+      "stopping",
+      "Tunnel process termination was confirmed, but local port ownership could not be rechecked. On macOS, install lsof to restore that diagnostic."
+    );
+  }
+  await cleanupFinishedSession(session);
+  if (emitStopped) {
+    emitSafely(emit, "stopped");
+  }
+}
+function assertTunnelRunning(state, session) {
+  if (state.child !== void 0 && childIsOpen2(state.child) && !state.childFailed) {
+    return;
+  }
+  throw new CfDebuggerError(
+    "TUNNEL_NOT_READY",
+    `SSH tunnel for session ${session.sessionId} exited before readiness could be committed.`,
+    state.child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(state.child))
+  );
+}
+function createTunnelLifecycle(session, emit) {
+  const initialized = initializeTunnelLifecycle();
+  const { state } = initialized;
   return {
-    exitPromise,
+    exitPromise: initialized.exitPromise,
     assertRunning: () => {
-      if (child === void 0 || !childIsOpen(child) || childFailed) {
-        throw new CfDebuggerError(
-          "TUNNEL_NOT_READY",
-          `SSH tunnel for session ${session.sessionId} exited before readiness could be committed.`,
-          child === void 0 ? void 0 : formatTunnelDiagnostics(getTunnelDiagnostics(child))
-        );
-      }
+      assertTunnelRunning(state, session);
+    },
+    finalize: async (emitStopped) => {
+      await finalizeTunnelLifecycle(state, session, emit, emitStopped);
+    },
+    observeChild: (child) => {
+      observeTunnelChild(state, session.sessionId, child, emit);
     },
-    finalize,
-    observeChild,
-    failed: () => childFailed,
-    error: () => tunnelError
+    failed: () => state.childFailed,
+    error: () => state.tunnelError
   };
 }
 function createDebuggerHandle(session, emit, lifecycle) {
@@ -3245,7 +3762,7 @@ function throwIfStartupAborted(signal, expiresAt, timeoutMs, phase) {
 
 // src/debug-session/start.ts
 import { chmod as chmod4, mkdir as mkdir4 } from "fs/promises";
-import nodeProcess6 from "process";
+import nodeProcess7 from "process";
 
 // src/debug-session/orphans.ts
 import { readdir as readdir2, stat as stat2, unlink as unlink4 } from "fs/promises";
@@ -3288,6 +3805,16 @@ async function pruneAndCleanupOrphans(stateAccess) {
 
 // src/debug-session/startup-cancellation.ts
 var STOP_REQUEST_POLL_MS = 500;
+async function startupStopWasRequested(sessionId) {
+  try {
+    if (await hasSessionStopIntent(sessionId)) {
+      return true;
+    }
+  } catch {
+  }
+  const stateVerdict = await inspectSessionStateStopIntent(sessionId);
+  return stateVerdict === "missing" || stateVerdict === "requested";
+}
 function createStartupCancellation(sessionId, callerSignal) {
   const controller = new AbortController();
   let active = true;
@@ -3303,7 +3830,7 @@ function createStartupCancellation(sessionId, callerSignal) {
   };
   const poll = async () => {
     try {
-      if (active && await hasSessionStopIntent(sessionId)) {
+      if (active && await startupStopWasRequested(sessionId)) {
         controller.abort();
       }
     } catch {
@@ -3487,6 +4014,8 @@ async function signalRemoteNode(inputs) {
 }
 
 // src/debug-session/startup-tunnel.ts
+var INSPECTOR_READY_RESERVE_MS = 1e4;
+var OWNER_READY_ATTEMPT_MAX_MS = 5e3;
 function linkAbortSignals(signals) {
   const controller = new AbortController();
   const subscriptions = [];
@@ -3510,6 +4039,35 @@ function linkAbortSignals(signals) {
     }
   };
 }
+function observeChildExit(child) {
+  let listening = true;
+  let resolveExit;
+  const onClose = () => {
+    listening = false;
+    resolveExit?.();
+  };
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return {
+      promise: Promise.resolve(),
+      dispose: () => {
+        child.removeListener("close", onClose);
+      }
+    };
+  }
+  const promise = new Promise((resolve) => {
+    resolveExit = resolve;
+    child.once("close", onClose);
+  });
+  return {
+    promise,
+    dispose: () => {
+      if (listening) {
+        listening = false;
+        child.removeListener("close", onClose);
+      }
+    }
+  };
+}
 function diagnosticsStderr(child) {
   return formatTunnelDiagnostics(getTunnelDiagnostics(child));
 }
@@ -3530,6 +4088,33 @@ function remainingReadyTimeout(inputs) {
     Math.min(inputs.tunnelReadyTimeoutMs, inputs.context.deadlineAt - Date.now())
   );
 }
+function createReadyWindow(timeoutMs) {
+  const totalMs = Math.max(1, timeoutMs);
+  const inspectorReserveMs = Math.min(
+    INSPECTOR_READY_RESERVE_MS,
+    Math.floor(totalMs / 2)
+  );
+  const ownerReserveMs = Math.min(
+    OWNER_READY_ATTEMPT_MAX_MS * 2,
+    Math.floor((totalMs - inspectorReserveMs) / 2)
+  );
+  const ownerTimeoutMs = Math.max(1, Math.floor(ownerReserveMs / 2));
+  return {
+    deadlineAt: Date.now() + totalMs,
+    finalOwnerReserveMs: ownerTimeoutMs,
+    localTimeoutMs: Math.max(1, totalMs - inspectorReserveMs - ownerReserveMs),
+    ownerTimeoutMs
+  };
+}
+function remainingWindowMs(window) {
+  return Math.max(0, window.deadlineAt - Date.now());
+}
+function remainingInspectorMs(window) {
+  return Math.max(
+    1,
+    remainingWindowMs(window) - window.finalOwnerReserveMs
+  );
+}
 function startupStateAccess(inputs) {
   return {
     ...inputs.context.signal === void 0 ? {} : { signal: inputs.context.signal },
@@ -3554,6 +4139,7 @@ function ownerVerificationError(localPort, inspection, child) {
 }
 async function waitForLocalTunnel(inputs, child, timeoutMs) {
   const childEnded = new AbortController();
+  const childExit = observeChildExit(child);
   const linked = linkAbortSignals([
     ...inputs.context.signal === void 0 ? [] : [inputs.context.signal],
     childEnded.signal
@@ -3562,7 +4148,7 @@ async function waitForLocalTunnel(inputs, child, timeoutMs) {
     const probe = probeTunnelReady(inputs.session.localPort, timeoutMs, linked.signal);
     const winner = await Promise.race([
       probe.then((ready) => ({ kind: "probe", ready })),
-      childExitPromise(child).then(() => ({ kind: "child-exit" }))
+      childExit.promise.then(() => ({ kind: "child-exit" }))
     ]);
     if (winner.kind === "probe" && winner.ready) {
       return;
@@ -3571,37 +4157,48 @@ async function waitForLocalTunnel(inputs, child, timeoutMs) {
       childEnded.abort();
       await probe.catch(() => false);
     }
+  } finally {
+    childExit.dispose();
+    linked.dispose();
+  }
+  throw new CfDebuggerError(
+    "TUNNEL_NOT_READY",
+    `SSH tunnel on local port ${inputs.session.localPort.toString()} did not bind within ${Math.round(timeoutMs / 1e3).toString()}s.`,
+    diagnosticsStderr(child)
+  );
+}
+async function verifyLocalOwner(inputs, child, childPid, timeoutMs) {
+  const phaseTimeout = AbortSignal.timeout(Math.max(1, Math.floor(timeoutMs)));
+  const linked = linkAbortSignals([
+    ...inputs.context.signal === void 0 ? [] : [inputs.context.signal],
+    phaseTimeout
+  ]);
+  let ownership;
+  try {
+    ownership = await inspectPortOwnership(
+      inputs.session.localPort,
+      childPid,
+      linked.signal
+    );
+  } catch (error) {
+    if (phaseTimeout.aborted && inputs.context.signal?.aborted !== true) {
+      ownership = {
+        status: "unverified",
+        reason: `ownership inspection exceeded its ${Math.round(timeoutMs).toString()}ms readiness budget`
+      };
+    } else {
+      throw error;
+    }
   } finally {
     linked.dispose();
   }
-  throw new CfDebuggerError(
-    "TUNNEL_NOT_READY",
-    `SSH tunnel on local port ${inputs.session.localPort.toString()} did not bind within ${Math.round(timeoutMs / 1e3).toString()}s.`,
-    diagnosticsStderr(child)
-  );
-}
-async function verifyLocalOwner(inputs, child, childPid) {
-  const ownership = await inspectPortOwnership(
-    inputs.session.localPort,
-    childPid,
-    inputs.context.signal
-  );
   if (ownership.status !== "owned") {
     throw ownerVerificationError(inputs.session.localPort, ownership, child);
   }
 }
-function childExitPromise(child) {
-  if (child.exitCode !== null || child.signalCode !== null) {
-    return Promise.resolve();
-  }
-  return new Promise((resolve) => {
-    child.once("close", () => {
-      resolve();
-    });
-  });
-}
 async function verifyInspector(inputs, child, timeoutMs) {
   const childEnded = new AbortController();
+  const childExit = observeChildExit(child);
   const linked = linkAbortSignals([
     ...inputs.context.signal === void 0 ? [] : [inputs.context.signal],
     childEnded.signal
@@ -3610,7 +4207,7 @@ async function verifyInspector(inputs, child, timeoutMs) {
     const probe = probeInspectorReady(inputs.session.localPort, timeoutMs, linked.signal);
     const winner = await Promise.race([
       probe.then((result) => ({ kind: "probe", result })),
-      childExitPromise(child).then(() => ({ kind: "child-exit" }))
+      childExit.promise.then(() => ({ kind: "child-exit" }))
     ]);
     if (winner.kind === "probe" && winner.result.status === "ready") {
       return;
@@ -3620,6 +4217,7 @@ async function verifyInspector(inputs, child, timeoutMs) {
       await probe.catch(() => ({ status: "unreachable" }));
     }
   } finally {
+    childExit.dispose();
     linked.dispose();
   }
   throw new CfDebuggerError(
@@ -3677,15 +4275,14 @@ async function openReadyTunnel(inputs) {
   inputs.onChild(child);
   const childPid = requireChildPid(child);
   await recordTunnelPid(inputs, childPid);
-  const timeoutMs = remainingReadyTimeout(inputs);
-  const readyDeadline = Date.now() + timeoutMs;
-  await waitForLocalTunnel(inputs, child, timeoutMs);
+  const readyWindow = createReadyWindow(remainingReadyTimeout(inputs));
+  await waitForLocalTunnel(inputs, child, readyWindow.localTimeoutMs);
   ensureStartupActive(inputs, "local tunnel binding");
-  await verifyLocalOwner(inputs, child, childPid);
+  await verifyLocalOwner(inputs, child, childPid, readyWindow.ownerTimeoutMs);
   ensureStartupActive(inputs, "local tunnel ownership verification");
-  await verifyInspector(inputs, child, Math.max(1, readyDeadline - Date.now()));
+  await verifyInspector(inputs, child, remainingInspectorMs(readyWindow));
   ensureStartupActive(inputs, "inspector readiness verification");
-  await verifyLocalOwner(inputs, child, childPid);
+  await verifyLocalOwner(inputs, child, childPid, remainingWindowMs(readyWindow));
   ensureStartupActive(inputs, "final local tunnel ownership verification");
   if (child.exitCode !== null || child.signalCode !== null) {
     throw new CfDebuggerError(
@@ -3697,9 +4294,17 @@ async function openReadyTunnel(inputs) {
 }
 
 // src/debug-session/start.ts
+function validateStartTarget(options) {
+  return {
+    ...options,
+    app: validateCfCliOperand(options.app, "app"),
+    org: validateCfCliOperand(options.org, "org"),
+    space: validateCfCliOperand(options.space, "space")
+  };
+}
 function requireCredentials(options) {
-  const email = options.email ?? nodeProcess6.env["SAP_EMAIL"];
-  const password = options.password ?? nodeProcess6.env["SAP_PASSWORD"];
+  const email = options.email ?? nodeProcess7.env["SAP_EMAIL"];
+  const password = options.password ?? nodeProcess7.env["SAP_PASSWORD"];
   if (email === void 0 || email.length === 0) {
     throw new CfDebuggerError(
       "MISSING_CREDENTIALS",
@@ -3885,11 +4490,11 @@ async function establishDebuggerSession(inputs) {
   return readySession;
 }
 function writeWarning(message) {
-  nodeProcess6.stderr.write(`[cf-debugger] warning: ${message}
+  nodeProcess7.stderr.write(`[cf-debugger] warning: ${message}
 `);
 }
 function writeTunnelOutput(stream, text) {
-  nodeProcess6.stderr.write(`[cf-debugger tunnel ${stream}] ${text}
+  nodeProcess7.stderr.write(`[cf-debugger tunnel ${stream}] ${text}
 `);
 }
 function retryMessage(status) {
@@ -3931,59 +4536,102 @@ function normalizeStartupError(error, expiresAt, timeoutMs) {
   }
   return error;
 }
+function resolveStartupPlan(options) {
+  const validatedOptions = validateStartTarget(options);
+  const restartAllowed = applyRestartEnvironmentVeto(
+    validatedOptions.allowSshEnableRestart,
+    nodeProcess7.env["CF_DEBUGGER_ALLOW_RESTART"]
+  );
+  const effectiveOptions = restartAllowed === validatedOptions.allowSshEnableRestart ? validatedOptions : { ...validatedOptions, allowSshEnableRestart: restartAllowed };
+  const target = resolveNodeTarget(effectiveOptions);
+  const credentials = requireCredentials(effectiveOptions);
+  const apiEndpoint = resolveApiEndpoint(
+    effectiveOptions.region,
+    effectiveOptions.apiEndpoint,
+    writeWarning
+  );
+  const tunnelReadyTimeoutMs = resolveTunnelReadyTimeoutMs(
+    effectiveOptions.tunnelReadyTimeoutMs
+  );
+  return {
+    apiEndpoint,
+    credentials,
+    options: effectiveOptions,
+    target,
+    tracker: createStatusTracker(effectiveOptions),
+    tunnelReadyTimeoutMs
+  };
+}
+async function completeStartup(plan, deadline, resources) {
+  throwIfStartupAborted(
+    deadline.signal,
+    deadline.expiresAt,
+    deadline.timeoutMs,
+    "initialization"
+  );
+  await pruneAndCleanupOrphans(startupStateAccess2(deadline.signal, deadline.expiresAt));
+  throwIfStartupAborted(
+    deadline.signal,
+    deadline.expiresAt,
+    deadline.timeoutMs,
+    "state cleanup"
+  );
+  const session = await registerSession(
+    plan.options,
+    plan.target,
+    plan.apiEndpoint,
+    deadline
+  );
+  resources.cancellation = createStartupCancellation(session.sessionId, deadline.signal);
+  const context = createCfContext(
+    session,
+    plan.credentials,
+    resources.cancellation,
+    deadline,
+    plan.tracker,
+    plan.options.verbose === true
+  );
+  resources.lifecycle = createTunnelLifecycle(session, plan.tracker.emit);
+  const activeSession = await establishDebuggerSession({
+    options: { ...plan.options, remotePort: session.remotePort },
+    target: plan.target,
+    session,
+    context,
+    credentials: plan.credentials,
+    tunnelReadyTimeoutMs: plan.tunnelReadyTimeoutMs,
+    emit: plan.tracker.emit,
+    transition: createTransition(session.sessionId, context),
+    lifecycle: resources.lifecycle
+  });
+  resources.cancellation.dispose();
+  deadline.dispose();
+  return createDebuggerHandle(activeSession, plan.tracker.emit, resources.lifecycle);
+}
+async function handleStartupFailure(error, plan, resources, deadline) {
+  resources.cancellation?.dispose();
+  deadline.dispose();
+  const normalized = normalizeStartupError(
+    error,
+    deadline.expiresAt,
+    deadline.timeoutMs
+  );
+  if (resources.lifecycle !== void 0) {
+    return await cleanupFailedStartup(normalized, resources.lifecycle, plan.tracker.emit);
+  }
+  plan.tracker.emit(
+    "error",
+    normalized instanceof Error ? normalized.message : String(normalized)
+  );
+  throw normalized;
+}
 async function startDebuggerUsingDeadline(options, deadline) {
-  const target = resolveNodeTarget(options);
-  const credentials = requireCredentials(options);
-  const apiEndpoint = resolveApiEndpoint(options.region, options.apiEndpoint, writeWarning);
-  const startupTimeoutMs = deadline.timeoutMs;
-  const tunnelReadyTimeoutMs = resolveTunnelReadyTimeoutMs(options.tunnelReadyTimeoutMs);
-  const tracker = createStatusTracker(options);
-  tracker.emit("starting");
-  let cancellation;
-  let lifecycle;
+  const plan = resolveStartupPlan(options);
+  const resources = {};
+  plan.tracker.emit("starting");
   try {
-    throwIfStartupAborted(deadline.signal, deadline.expiresAt, startupTimeoutMs, "initialization");
-    await pruneAndCleanupOrphans(
-      startupStateAccess2(deadline.signal, deadline.expiresAt)
-    );
-    throwIfStartupAborted(deadline.signal, deadline.expiresAt, startupTimeoutMs, "state cleanup");
-    const session = await registerSession(options, target, apiEndpoint, deadline);
-    cancellation = createStartupCancellation(session.sessionId, deadline.signal);
-    const context = createCfContext(
-      session,
-      credentials,
-      cancellation,
-      deadline,
-      tracker,
-      options.verbose === true
-    );
-    lifecycle = createTunnelLifecycle(session, tracker.emit);
-    const activeSession = await establishDebuggerSession({
-      options: { ...options, remotePort: session.remotePort },
-      target,
-      session,
-      context,
-      credentials,
-      tunnelReadyTimeoutMs,
-      emit: tracker.emit,
-      transition: createTransition(session.sessionId, context),
-      lifecycle
-    });
-    cancellation.dispose();
-    deadline.dispose();
-    return createDebuggerHandle(activeSession, tracker.emit, lifecycle);
+    return await completeStartup(plan, deadline, resources);
   } catch (error) {
-    cancellation?.dispose();
-    deadline.dispose();
-    const normalized = normalizeStartupError(error, deadline.expiresAt, startupTimeoutMs);
-    if (lifecycle === void 0) {
-      tracker.emit(
-        "error",
-        normalized instanceof Error ? normalized.message : String(normalized)
-      );
-      throw normalized;
-    }
-    return await cleanupFailedStartup(normalized, lifecycle, tracker.emit);
+    return await handleStartupFailure(error, plan, resources, deadline);
   }
 }
 async function startDebuggerWithinDeadline(options, deadline) {
@@ -4002,31 +4650,261 @@ async function startDebugger(options) {
 
 // src/debug-session/doctor.ts
 import {
-  lstat,
-  readFile as readFile5,
-  readdir as readdir3,
+  lstat as lstat3,
+  readFile as readFile7,
+  readdir as readdir5,
   unlink as unlink5
 } from "fs/promises";
-import { hostname as hostname2 } from "os";
+import { hostname as hostname4 } from "os";
+import { join as join5 } from "path";
+import nodeProcess10 from "process";
+
+// src/debug-session/doctor-homes.ts
+import { readdir as readdir3 } from "fs/promises";
 import { join as join3 } from "path";
-import nodeProcess7 from "process";
+function entryReason(symbolicLink, directory, cleanupEligible) {
+  if (symbolicLink) {
+    return "entry is a symbolic link, not a debugger CF home directory";
+  }
+  if (!directory) {
+    return "entry is not a directory";
+  }
+  return cleanupEligible ? void 0 : "entry name is not a safe debugger session ID";
+}
+async function discoverOrphanHomes(sessions) {
+  const root = join3(saptoolsDir(), CF_DEBUGGER_HOMES_DIRNAME);
+  const rootInspection = await inspectSessionHomesRoot(root);
+  if (rootInspection.status === "unsafe") {
+    return { candidates: [], warnings: [rootInspection.reason] };
+  }
+  if (rootInspection.status === "absent") {
+    return { candidates: [], warnings: [] };
+  }
+  const claimed = new Set(sessions.map((session) => session.sessionId));
+  const entries = await readdir3(root, { withFileTypes: true });
+  const candidates = entries.filter((entry) => !entry.isDirectory() || !claimed.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => {
+    const path = join3(root, entry.name);
+    const cleanupEligible = entry.isDirectory() && isOwnedSessionCfHomeDir(entry.name, path);
+    const reason = entryReason(
+      entry.isSymbolicLink(),
+      entry.isDirectory(),
+      cleanupEligible
+    );
+    return {
+      sessionId: entry.name,
+      path,
+      cleanupEligible,
+      ...reason === void 0 ? {} : { reason }
+    };
+  });
+  return { candidates, warnings: [] };
+}
+
+// src/debug-session/doctor-legacy.ts
+import { lstat as lstat2, readFile as readFile6, readdir as readdir4 } from "fs/promises";
+import { hostname as hostname2 } from "os";
+import { join as join4 } from "path";
+import nodeProcess8 from "process";
+var LEGACY_STATE_FILENAME = "cf-debugger-state.json";
+var LEGACY_LOCK_FILENAME = "cf-debugger-state.lock";
+var LEGACY_HOMES_DIRNAME = "cf-debugger-homes";
+function errorCode8(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" ? code : void 0;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function field3(value, key) {
+  return Reflect.get(value, key);
+}
+function optionalText(value, key) {
+  const candidate = field3(value, key);
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : void 0;
+}
+function optionalInteger2(value, key, maximum = Number.MAX_SAFE_INTEGER) {
+  const candidate = field3(value, key);
+  return typeof candidate === "number" && Number.isSafeInteger(candidate) && candidate > 0 && candidate <= maximum ? candidate : void 0;
+}
+function inspectLegacyPid(pid) {
+  try {
+    nodeProcess8.kill(pid, 0);
+    return {
+      liveness: "alive",
+      reason: "PID exists, but v1 state cannot prove process identity or tunnel ownership"
+    };
+  } catch (error) {
+    if (errorCode8(error) === "ESRCH") {
+      return { liveness: "not-running" };
+    }
+    return {
+      liveness: "unverified",
+      reason: `PID liveness check failed: ${errorMessage(error)}`
+    };
+  }
+}
+function parseLegacySession(value, index) {
+  if (typeof value !== "object" || value === null) {
+    return { index, liveness: "unverified", reason: "legacy session entry is not an object" };
+  }
+  const sessionId = optionalText(value, "sessionId");
+  const pid = optionalInteger2(value, "pid");
+  const localPort = optionalInteger2(value, "localPort", 65535);
+  const ownerHostname = optionalText(value, "hostname");
+  const fields = {
+    index,
+    ...sessionId === void 0 ? {} : { sessionId },
+    ...pid === void 0 ? {} : { pid },
+    ...localPort === void 0 ? {} : { localPort },
+    ...ownerHostname === void 0 ? {} : { hostname: ownerHostname }
+  };
+  if (pid === void 0 || ownerHostname === void 0) {
+    return {
+      ...fields,
+      liveness: "unverified",
+      reason: pid === void 0 ? "legacy session has no valid PID" : "legacy session has no valid hostname"
+    };
+  }
+  if (ownerHostname !== hostname2()) {
+    return {
+      ...fields,
+      liveness: "unverified",
+      reason: `legacy session belongs to host ${ownerHostname}; local PID was not probed`
+    };
+  }
+  return { ...fields, ...inspectLegacyPid(pid) };
+}
+async function inspectLegacyState(path) {
+  let raw;
+  try {
+    raw = await readFile6(path, "utf8");
+  } catch (error) {
+    return errorCode8(error) === "ENOENT" ? { present: false } : { present: true, warning: `Could not read legacy v1 state: ${errorMessage(error)}` };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { present: true, warning: "Legacy v1 state contains invalid JSON." };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { present: true, warning: "Legacy v1 state is not an object." };
+  }
+  const sessions = field3(parsed, "sessions");
+  if (field3(parsed, "version") !== "1" || !Array.isArray(sessions)) {
+    return { present: true, warning: "Legacy v1 state has an invalid structure." };
+  }
+  return {
+    present: true,
+    sessions: sessions.map(parseLegacySession)
+  };
+}
+async function inspectLegacyHomes(path) {
+  let stats;
+  try {
+    stats = await lstat2(path);
+  } catch (error) {
+    return errorCode8(error) === "ENOENT" ? { present: false, homeCount: 0 } : { present: true, warning: `Could not inspect legacy v1 homes: ${errorMessage(error)}` };
+  }
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    return {
+      present: true,
+      warning: "Legacy v1 homes root is not a real directory; it was not traversed."
+    };
+  }
+  try {
+    const entries = await readdir4(path, { withFileTypes: true });
+    return {
+      present: true,
+      homeCount: entries.filter((entry) => entry.isDirectory()).length
+    };
+  } catch (error) {
+    return {
+      present: true,
+      warning: `Could not enumerate legacy v1 homes: ${errorMessage(error)}`
+    };
+  }
+}
+function shellQuoteForCommand(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+async function findLegacyArtifacts() {
+  const statePath = join4(saptoolsDir(), LEGACY_STATE_FILENAME);
+  const lockPath = join4(saptoolsDir(), LEGACY_LOCK_FILENAME);
+  const homesPath = join4(saptoolsDir(), LEGACY_HOMES_DIRNAME);
+  const [state, homes] = await Promise.all([
+    inspectLegacyState(statePath),
+    inspectLegacyHomes(homesPath)
+  ]);
+  const inspectionWarnings = [state.warning, homes.warning].filter(
+    (warning) => warning !== void 0
+  );
+  const base = {
+    statePath,
+    statePresent: state.present,
+    homesPath,
+    homesPresent: homes.present,
+    ...homes.homeCount === void 0 ? {} : { homeCount: homes.homeCount },
+    ...state.sessions === void 0 ? {} : { sessions: state.sessions },
+    ...inspectionWarnings.length === 0 ? {} : { inspectionWarnings }
+  };
+  if (!state.present && !homes.present) {
+    return base;
+  }
+  return {
+    ...base,
+    warning: "Legacy v1 debugger homes may contain live CF refresh and access tokens. Confirm no reported v1 tunnel is running before removing them.",
+    manualRemovalCommand: `rm -rf -- ${shellQuoteForCommand(homesPath)} ${shellQuoteForCommand(statePath)} ${shellQuoteForCommand(lockPath)}`
+  };
+}
+
+// src/debug-session/doctor-session-health.ts
+import { hostname as hostname3 } from "os";
+import nodeProcess9 from "process";
+function missingIdentityCaveat(session) {
+  const identity = session.status === "ready" ? session.tunnelProcessIdentity : session.controllerProcessIdentity;
+  return (nodeProcess9.platform === "linux" || nodeProcess9.platform === "darwin") && identity === void 0 ? "process identity token is absent, so PID-only compatibility is in use; an older cf-debugger sharing this state file may have stripped the additive field" : void 0;
+}
+async function inspectDoctorSessions(sessions) {
+  const local = sessions.filter((session) => session.hostname === hostname3());
+  return await Promise.all(local.map(async (session) => {
+    try {
+      const health = await inspectSessionHealth(session);
+      const caveat = missingIdentityCaveat(session);
+      return {
+        session,
+        health: caveat === void 0 ? health : { ...health, reason: `${health.reason}; ${caveat}` }
+      };
+    } catch (error) {
+      return {
+        session,
+        health: {
+          status: "unverified",
+          reason: `health inspection failed: ${error instanceof Error ? error.message : String(error)}`
+        }
+      };
+    }
+  }));
+}
+
+// src/debug-session/doctor.ts
 var MANAGED_PORT_MIN = 2e4;
 var MANAGED_PORT_MAX = 20999;
 var PORT_SCAN_CONCURRENCY = 32;
 var STALE_TEMP_AGE_MS2 = 24 * 60 * 60 * 1e3;
 var STALE_LOCK_AGE_MS = 60 * 60 * 1e3;
 var FOREIGN_OR_MALFORMED_LOCK_AGE_MS = 24 * 60 * 60 * 1e3;
-var LEGACY_STATE_FILENAME = "cf-debugger-state.json";
-var LEGACY_LOCK_FILENAME = "cf-debugger-state.lock";
-var LEGACY_HOMES_DIRNAME = "cf-debugger-homes";
-function errorCode7(error) {
+function errorCode9(error) {
   if (typeof error !== "object" || error === null) {
     return void 0;
   }
   const value = Reflect.get(error, "code");
   return typeof value === "string" ? value : void 0;
 }
-function errorMessage(error) {
+function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function emptyState2() {
@@ -4035,14 +4913,14 @@ function emptyState2() {
 async function readDoctorState() {
   let raw;
   try {
-    raw = await readFile5(stateFilePath(), "utf8");
+    raw = await readFile7(stateFilePath(), "utf8");
   } catch (error) {
-    if (errorCode7(error) === "ENOENT") {
+    if (errorCode9(error) === "ENOENT") {
       return { state: emptyState2(), warnings: [], homeCleanupSafe: true };
     }
     return {
       state: emptyState2(),
-      warnings: [`Could not read debugger state: ${errorMessage(error)}`],
+      warnings: [`Could not read debugger state: ${errorMessage2(error)}`],
       homeCleanupSafe: false
     };
   }
@@ -4070,54 +4948,58 @@ async function readDoctorState() {
     homeCleanupSafe: decoded.dropped.length === 0
   };
 }
-async function inspectSessions(sessions) {
-  const local = sessions.filter((session) => session.hostname === hostname2());
-  return await Promise.all(local.map(async (session) => {
-    try {
-      return { session, health: await inspectSessionHealth(session) };
-    } catch (error) {
-      return {
-        session,
-        health: {
-          status: "unverified",
-          reason: `health inspection failed: ${errorMessage(error)}`
-        }
-      };
-    }
-  }));
-}
 async function readDirectory(path) {
   try {
-    return await readdir3(path, { withFileTypes: true });
+    return await readdir5(path, { withFileTypes: true });
   } catch (error) {
-    if (errorCode7(error) === "ENOENT") {
+    if (errorCode9(error) === "ENOENT") {
       return [];
     }
     throw error;
   }
 }
-async function findOrphanHomes(sessions, cleanup) {
-  const root = join3(saptoolsDir(), CF_DEBUGGER_HOMES_DIRNAME);
-  const claimed = new Set(sessions.map((session) => session.sessionId));
-  const entries = await readDirectory(root);
-  const orphans = entries.filter((entry) => entry.isDirectory() && !claimed.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
-  return await Promise.all(orphans.map(async (entry) => {
-    const path = join3(root, entry.name);
-    const cleanupEligible = isOwnedSessionCfHomeDir(entry.name, path);
-    if (!cleanup) {
-      return { sessionId: entry.name, path, cleanupEligible, cleanupStatus: "not-requested" };
-    }
-    if (!cleanupEligible) {
-      return { sessionId: entry.name, path, cleanupEligible, cleanupStatus: "not-eligible" };
+async function findOrphanHomes(sessions, cleanupRequested, cleanupSafe) {
+  const discovery = await discoverOrphanHomes(sessions);
+  const findings = await Promise.all(discovery.candidates.map(
+    async (candidate) => {
+      const { cleanupEligible, path, reason, sessionId } = candidate;
+      if (!cleanupRequested) {
+        return {
+          sessionId,
+          path,
+          cleanupEligible,
+          cleanupStatus: "not-requested",
+          ...reason === void 0 ? {} : { reason }
+        };
+      }
+      if (!cleanupSafe) {
+        return {
+          sessionId,
+          path,
+          cleanupEligible,
+          cleanupStatus: cleanupEligible ? "skipped" : "not-eligible",
+          ...reason === void 0 ? {} : { reason }
+        };
+      }
+      if (!cleanupEligible) {
+        return {
+          sessionId,
+          path,
+          cleanupEligible,
+          cleanupStatus: "not-eligible",
+          ...reason === void 0 ? {} : { reason }
+        };
+      }
+      const cleanupStatus = await cleanupOrphanHome(sessionId, path);
+      return {
+        sessionId,
+        path,
+        cleanupEligible,
+        cleanupStatus
+      };
     }
-    const cleanupStatus = await cleanupOrphanHome(entry.name, path);
-    return {
-      sessionId: entry.name,
-      path,
-      cleanupEligible,
-      cleanupStatus
-    };
-  }));
+  ));
+  return { findings, warnings: discovery.warnings };
 }
 async function cleanupOrphanHome(sessionId, path) {
   try {
@@ -4158,7 +5040,7 @@ async function mapConcurrent(values, concurrency, work) {
 }
 function unclaimedManagedPorts(sessions) {
   const localClaims = new Set(
-    sessions.filter((session) => session.hostname === hostname2()).map((session) => session.localPort)
+    sessions.filter((session) => session.hostname === hostname4()).map((session) => session.localPort)
   );
   const ports = [];
   for (let port = MANAGED_PORT_MIN; port <= MANAGED_PORT_MAX; port += 1) {
@@ -4235,15 +5117,15 @@ function parseLockOwner2(raw) {
 }
 function isPidAlive2(pid) {
   try {
-    nodeProcess7.kill(pid, 0);
+    nodeProcess10.kill(pid, 0);
     return true;
   } catch (error) {
-    return errorCode7(error) !== "ESRCH";
+    return errorCode9(error) !== "ESRCH";
   }
 }
 async function readLockOwner2(path) {
   try {
-    return parseLockOwner2(await readFile5(path, "utf8"));
+    return parseLockOwner2(await readFile7(path, "utf8"));
   } catch {
     return void 0;
   }
@@ -4253,7 +5135,7 @@ async function lockCleanupEligible(path, ageMs) {
     return false;
   }
   const owner = await readLockOwner2(path);
-  if (owner?.hostname === hostname2()) {
+  if (owner?.hostname === hostname4()) {
     if (!isPidAlive2(owner.pid)) {
       return true;
     }
@@ -4283,18 +5165,21 @@ async function inspectArtifact(entry, now, claimedSessionIds, stopIntentCleanupS
   if (kind === void 0) {
     return void 0;
   }
-  const path = join3(saptoolsDir(), entry.name);
-  const stats = await lstat(path);
+  const path = join5(saptoolsDir(), entry.name);
+  const stats = await lstat3(path);
   const ageMs = Math.max(0, now - stats.mtimeMs);
   const regularFile = stats.isFile();
   let sessionId;
   let cleanupEligible = regularFile && kind === "state-temp" && ageMs >= STALE_TEMP_AGE_MS2;
+  let cleanupBlocked = false;
   if (regularFile && kind === "stop-intent") {
     sessionId = entry.name.slice(
       CF_DEBUGGER_STOP_INTENT_PREFIX.length,
       -".stop".length
     );
-    cleanupEligible = stopIntentCleanupSafe && ageMs >= STALE_TEMP_AGE_MS2 && !claimedSessionIds.has(sessionId);
+    const otherwiseEligible = ageMs >= STALE_TEMP_AGE_MS2 && !claimedSessionIds.has(sessionId);
+    cleanupEligible = stopIntentCleanupSafe && otherwiseEligible;
+    cleanupBlocked = !stopIntentCleanupSafe && otherwiseEligible;
   }
   if (regularFile && (kind === "state-lock" || kind === "state-recovery")) {
     cleanupEligible = await lockCleanupEligible(path, ageMs);
@@ -4304,13 +5189,14 @@ async function inspectArtifact(entry, now, claimedSessionIds, stopIntentCleanupS
     path,
     ageMs,
     cleanupEligible,
+    cleanupBlocked,
     fingerprint: artifactFingerprint(stats),
     ...sessionId === void 0 ? {} : { sessionId }
   };
 }
 async function candidateStillMatches(candidate) {
   try {
-    const stats = await lstat(candidate.path);
+    const stats = await lstat3(candidate.path);
     return artifactFingerprint(stats) === candidate.fingerprint;
   } catch {
     return false;
@@ -4342,11 +5228,19 @@ async function cleanupArtifact(candidate) {
     await unlink5(candidate.path);
     return { status: "removed" };
   } catch (error) {
-    if (errorCode7(error) === "ENOENT") {
+    if (errorCode9(error) === "ENOENT") {
       return { status: "skipped" };
     }
-    return { status: "failed", error: errorMessage(error) };
+    return { status: "failed", error: errorMessage2(error) };
+  }
+}
+async function resolveArtifactCleanup(candidate, cleanup) {
+  if (!cleanup) {
+    return {
+      status: candidate.cleanupEligible ? "not-requested" : "not-eligible"
+    };
   }
+  return candidate.cleanupBlocked ? { status: "skipped" } : await cleanupArtifact(candidate);
 }
 async function findArtifacts(cleanup, sessions, stopIntentCleanupSafe) {
   const entries = await readDirectory(saptoolsDir());
@@ -4361,55 +5255,22 @@ async function findArtifacts(cleanup, sessions, stopIntentCleanupSafe) {
   ).sort((left, right) => left.path.localeCompare(right.path));
   const findings = [];
   for (const candidate of candidates) {
-    const result = cleanup ? await cleanupArtifact(candidate) : {
-      status: candidate.cleanupEligible ? "not-requested" : "not-eligible"
-    };
+    const result = await resolveArtifactCleanup(candidate, cleanup);
     findings.push({
       kind: candidate.kind,
       path: candidate.path,
       ageMs: candidate.ageMs,
       cleanupEligible: candidate.cleanupEligible,
       cleanupStatus: result.status,
-      ...result.error === void 0 ? {} : { cleanupError: result.error }
+      ...result.error === void 0 ? {} : { cleanupError: result.error },
+      ...candidate.kind === "corrupt-backup" ? {
+        note: "Preserved recovery evidence; it may contain debugger session metadata such as target names, PIDs, ports, and CF home paths. Inspect it before manual removal.",
+        manualRemovalCommand: `rm -- ${shellQuoteForCommand(candidate.path)}`
+      } : {}
     });
   }
   return findings;
 }
-async function pathExists(path) {
-  try {
-    await lstat(path);
-    return true;
-  } catch (error) {
-    if (errorCode7(error) === "ENOENT") {
-      return false;
-    }
-    throw error;
-  }
-}
-function shellQuote(value) {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-async function findLegacyArtifacts() {
-  const statePath = join3(saptoolsDir(), LEGACY_STATE_FILENAME);
-  const lockPath = join3(saptoolsDir(), LEGACY_LOCK_FILENAME);
-  const homesPath = join3(saptoolsDir(), LEGACY_HOMES_DIRNAME);
-  const [statePresent, homesPresent] = await Promise.all([
-    pathExists(statePath),
-    pathExists(homesPath)
-  ]);
-  if (!statePresent && !homesPresent) {
-    return { statePath, statePresent, homesPath, homesPresent };
-  }
-  const command = `rm -rf -- ${shellQuote(homesPath)} ${shellQuote(statePath)} ${shellQuote(lockPath)}`;
-  return {
-    statePath,
-    statePresent,
-    homesPath,
-    homesPresent,
-    warning: "Legacy v1 debugger homes may contain live CF refresh and access tokens. Confirm no v1 tunnel is running before removing them.",
-    manualRemovalCommand: command
-  };
-}
 function reportWarnings(stateWarnings, orphanHomes, unclaimedPorts, legacy) {
   const warnings = [...stateWarnings];
   if (orphanHomes.length > 0) {
@@ -4426,14 +5287,14 @@ function reportWarnings(stateWarnings, orphanHomes, unclaimedPorts, legacy) {
 async function runDoctor(options = {}) {
   const cleanup = options.cleanup === true;
   const stateResult = await readDoctorState();
-  const homeCleanup = cleanup && stateResult.homeCleanupSafe;
-  const [sessions, orphanHomes, unclaimedPorts, artifacts, legacy] = await Promise.all([
-    inspectSessions(stateResult.state.sessions),
-    findOrphanHomes(stateResult.state.sessions, homeCleanup),
+  const [sessions, homeInspection, unclaimedPorts, artifacts, legacy] = await Promise.all([
+    inspectDoctorSessions(stateResult.state.sessions),
+    findOrphanHomes(stateResult.state.sessions, cleanup, stateResult.homeCleanupSafe),
     findUnclaimedPorts(stateResult.state.sessions),
     findArtifacts(cleanup, stateResult.state.sessions, stateResult.homeCleanupSafe),
     findLegacyArtifacts()
   ]);
+  const orphanHomes = homeInspection.findings;
   const cleanedPaths = [
     ...orphanHomes.filter((finding) => finding.cleanupStatus === "removed").map((finding) => finding.path),
     ...artifacts.filter((finding) => finding.cleanupStatus === "removed").map((finding) => finding.path)
@@ -4446,6 +5307,7 @@ async function runDoctor(options = {}) {
     legacy,
     warnings: [
       ...reportWarnings(stateResult.warnings, orphanHomes, unclaimedPorts, legacy),
+      ...homeInspection.warnings,
       ...cleanup && !stateResult.homeCleanupSafe ? [
         "Skipped orphan-home and stop-intent cleanup because debugger state was incomplete or invalid."
       ] : []
@@ -4456,7 +5318,7 @@ async function runDoctor(options = {}) {
 
 // src/debug-session/sessions.ts
 import { hostname as getHostname4 } from "os";
-import nodeProcess8 from "process";
+import nodeProcess11 from "process";
 function findMatchingSession(sessions, options) {
   if (options.sessionId !== void 0) {
     return sessions.find((session) => session.sessionId === options.sessionId);
@@ -4474,50 +5336,55 @@ function findMatchingSession(sessions, options) {
   }
   return matches[0];
 }
-function startupAgeLimit2(session) {
-  return (session.startupTimeoutMs ?? MAX_STARTUP_TIMEOUT_MS) + STARTUP_STALE_SLACK_MS;
-}
-function startupExpired2(session) {
-  const startedAt = Date.parse(session.startedAt);
-  return Number.isNaN(startedAt) || Date.now() - startedAt > startupAgeLimit2(session);
-}
-async function inspectRecordedProcess2(pid, identity) {
-  if (!isPidAlive(pid)) {
-    return "dead";
-  }
-  return await inspectProcessIdentity(pid, identity);
-}
 async function inspectController(target) {
   const controllerPid = target.controllerPid ?? target.pid;
-  return await inspectRecordedProcess2(controllerPid, target.controllerProcessIdentity);
+  return await inspectRecordedProcess(
+    controllerPid,
+    target.controllerProcessIdentity,
+    isPidAlive
+  );
 }
 async function ownsRecordedTunnel(target) {
   const tunnelPid = target.tunnelPid;
   if (tunnelPid === void 0) {
     return false;
   }
-  const processVerdict = await inspectRecordedProcess2(
+  const processVerdict = await inspectRecordedProcess(
     tunnelPid,
-    target.tunnelProcessIdentity
+    target.tunnelProcessIdentity,
+    isPidAlive
   );
   if (processVerdict !== "match") {
     return false;
   }
   return (await inspectPortOwnership(target.localPort, tunnelPid)).status === "owned";
 }
-async function terminateVerifiedTunnel(target) {
+async function terminateVerifiedTunnel(target, recordExpectedStop) {
   const tunnelPid = target.tunnelPid;
-  if (tunnelPid === void 0 || tunnelPid === nodeProcess8.pid) {
-    return tunnelPid === nodeProcess8.pid ? "still-alive" : "terminated";
+  if (tunnelPid === void 0 || tunnelPid === nodeProcess11.pid) {
+    return tunnelPid === nodeProcess11.pid ? "still-alive" : "terminated";
   }
+  let stopIntentRecorded = false;
   try {
     const verifyBeforeSignal = async (signal) => {
       if (signal === "SIGTERM" || target.tunnelProcessIdentity === void 0) {
-        return await ownsRecordedTunnel(target);
+        if (!await ownsRecordedTunnel(target)) {
+          return false;
+        }
+        if (recordExpectedStop && !stopIntentRecorded) {
+          const claim = await requestSessionStop(target.sessionId);
+          if (claim === void 0) {
+            return false;
+          }
+          stopIntentRecorded = true;
+          return await ownsRecordedTunnel(target);
+        }
+        return true;
       }
-      return await inspectRecordedProcess2(
+      return await inspectRecordedProcess(
         tunnelPid,
-        target.tunnelProcessIdentity
+        target.tunnelProcessIdentity,
+        isPidAlive
       ) === "match";
     };
     return await terminatePidOrGroup(
@@ -4531,13 +5398,10 @@ async function terminateVerifiedTunnel(target) {
   }
 }
 async function terminateVerifiedTunnelAndConfirm(target, recordExpectedStop = false) {
-  if (recordExpectedStop) {
-    await writeSessionStopIntent(target.sessionId);
-  }
   if (!await ownsRecordedTunnel(target)) {
     throw ownershipError(target, "recorded tunnel no longer owns the local port");
   }
-  const termination = await terminateVerifiedTunnel(target);
+  const termination = await terminateVerifiedTunnel(target, recordExpectedStop);
   if (termination !== "terminated" || await ownsRecordedTunnel(target)) {
     throw new CfDebuggerError(
       "TUNNEL_TERMINATION_FAILED",
@@ -4547,18 +5411,26 @@ async function terminateVerifiedTunnelAndConfirm(target, recordExpectedStop = fa
 }
 async function removeOwnedSession(target, stale, forced = false, warning, preserveStopIntent = false) {
   let resultWarning = warning;
-  if (isOwnedSessionCfHomeDir(target.sessionId, target.cfHomeDir)) {
-    await removeOwnedSessionCfHome(target.sessionId, target.cfHomeDir);
-  } else {
+  const cleanup = await forgetSessionThenCleanupHome(target);
+  if (cleanup.homeStatus === "retained") {
+    const retained = `The session record was removed, but its owned CF home ${target.cfHomeDir} could not be deleted and may still hold a live CF refresh token; remove it manually or run \`cf-debugger doctor --cleanup\`.`;
+    resultWarning = appendWarning(resultWarning, retained);
+  } else if (cleanup.homeStatus === "unowned") {
     const skipped = `State referenced unowned CF home ${target.cfHomeDir}; it was not deleted.`;
-    resultWarning = resultWarning === void 0 ? skipped : `${resultWarning} ${skipped}`;
+    resultWarning = appendWarning(resultWarning, skipped);
   }
-  const removed = await removeSession(target.sessionId);
   if (!preserveStopIntent) {
-    await clearSessionStopIntent(target.sessionId);
+    try {
+      await clearSessionStopIntent(target.sessionId);
+    } catch {
+      resultWarning = appendWarning(
+        resultWarning,
+        `The session record was removed, but its stop-intent artifact could not be deleted; run \`cf-debugger doctor --cleanup\` after resolving the filesystem error.`
+      );
+    }
   }
   return {
-    ...removed ?? target,
+    ...cleanup.removed ?? target,
     stale,
     pending: false,
     forced,
@@ -4574,6 +5446,9 @@ function ownershipError(target, detail) {
 function forcedWarning(target, detail) {
   return `Forced state cleanup abandoned PID ${String(target.tunnelPid ?? target.controllerPid ?? target.pid)} and local port ${target.localPort.toString()}: ${detail}. No unverified process was signalled.`;
 }
+function appendWarning(current, next) {
+  return current === void 0 ? next : `${current} ${next}`;
+}
 async function forceRemoveUnverified(target, detail, preserveStopIntent = false) {
   return await removeOwnedSession(
     target,
@@ -4588,20 +5463,24 @@ async function stopReadySession(target, force) {
     await terminateVerifiedTunnelAndConfirm(target, true);
     return await removeOwnedSession(target, false, false, void 0, true);
   }
-  const tunnelVerdict = target.tunnelPid === void 0 ? "dead" : await inspectRecordedProcess2(target.tunnelPid, target.tunnelProcessIdentity);
+  const tunnelVerdict = target.tunnelPid === void 0 ? "dead" : await inspectRecordedProcess(
+    target.tunnelPid,
+    target.tunnelProcessIdentity,
+    isPidAlive
+  );
   const tunnelDead = target.tunnelPid === void 0 || !isPidOrGroupAlive(target.tunnelPid) || tunnelVerdict === "mismatch";
   const ownership = target.tunnelPid === void 0 ? await inspectListeningProcesses(target.localPort) : await inspectPortOwnership(target.localPort, target.tunnelPid);
   if (tunnelDead && ownership.status === "not-listening") {
-    return await removeOwnedSession(target, true, false, void 0, true);
+    return await removeOwnedSession(target, true);
   }
   const detail = ownership.status === "unverified" ? ownership.reason : ownership.status === "not-owned" ? `local port ${target.localPort.toString()} belongs to PID(s) ${ownership.pids.join(", ")}` : tunnelVerdict === "unavailable" ? "the recorded tunnel identity could not be inspected" : "the recorded tunnel could not be proven dead and owned";
   if (force) {
-    return await forceRemoveUnverified(target, detail, true);
+    return await forceRemoveUnverified(target, detail);
   }
   throw ownershipError(target, detail);
 }
 async function stopStartingSession(target, force) {
-  const expired = startupExpired2(target);
+  const expired = startupExpired(target);
   const controllerVerdict = await inspectController(target);
   if (!force && !expired && controllerVerdict === "match") {
     return { ...target, stale: false, pending: true, forced: false };
@@ -4633,17 +5512,20 @@ async function stopDebugger(options) {
   if (target === void 0) {
     return void 0;
   }
+  if (target.status === "ready") {
+    return await stopReadySession(target, options.force === true);
+  }
   const claim = await requestSessionStop(target.sessionId);
   if (claim === void 0) {
     return void 0;
   }
-  return claim.previousStatus === "ready" ? await stopReadySession(claim.session, options.force === true) : await stopStartingSession(claim.session, options.force === true);
+  return await stopStartingSession(claim.session, options.force === true);
 }
 function outcomeForResult(result) {
   return {
     sessionId: result.sessionId,
     app: result.app,
-    status: result.pending ? "pending" : result.stale ? "stale" : "stopped",
+    status: result.pending ? "pending" : result.forced ? "forced" : result.stale ? "stale" : "stopped",
     result
   };
 }
@@ -4671,6 +5553,7 @@ function summarizeOutcomes(outcomes) {
   return {
     outcomes,
     failed: count("failed"),
+    forced: count("forced"),
     pending: count("pending"),
     stale: count("stale"),
     stopped: count("stopped")
@@ -4703,6 +5586,7 @@ async function getSession(key) {
 
 export {
   CfDebuggerError,
+  validateApiEndpointOverride,
   resolveApiEndpoint,
   listKnownRegionKeys,
   readCurrentCfTarget,
@@ -4714,10 +5598,12 @@ export {
   resolveNodeTarget,
   buildNodeInspectorCommand,
   parseNodeInspectorMarkers,
+  parseRestartEnvironment,
   sessionKeyString,
   CLEANUP_FAILURE_EXIT_CODE,
   hasTunnelTerminationFailure,
   cliErrorExitCode,
+  stopAllExitCode,
   getDebuggerHandleTunnelError,
   resolveStartupTimeoutMs,
   remainingStartupMs,
@@ -4731,4 +5617,4 @@ export {
   listSessions,
   getSession
 };
-//# sourceMappingURL=chunk-ZWAQD7KL.js.map
+//# sourceMappingURL=chunk-QBB4N2WN.js.map