@@ -238,7 +238,7 @@ The codebase follows a **layered architecture with dependency injection** and **
      - `SessionManager` (`session-manager.ts`): Final composition class that extends SessionManagerOperations. Implements `handleAutoContinue(sessionId)` which auto-continues past entry breakpoints when `stopOnEntry=false`
    - `SessionManagerOperations` is itself a facade over per-slice collaborators, wired as protected fields and always reached at call time (`this.breakpoints.…`):
      - `launch/proxy-launcher.ts` (`ProxyLauncher.start(session, request)`, the one proxy launch both launch and attach go through): adapter creation under an `AdapterLease`, the configuration transform, executable resolution, `ProxyConfig` assembly; `launch/proxy-failure-diagnostics.ts` (`failProxySetup`/`logProxyFailure`): the shared failure teardown and record
-     - `launch/debug-launcher.ts` (`DebugLauncher`): `startDebugging` (dry runs included), `restartDebugging`; `launch/launch-readiness.ts` (`waitForLaunchReadiness`): the post-handshake wait for the first stop / configured / termination
+     - `launch/debug-launcher.ts` (`DebugLauncher`): `startDebugging` (dry runs included), `restartDebugging`; `launch/launch-readiness.ts` (`waitForLaunchReadiness`): the post-handshake wait for the first stop / configured / termination / the caller's ceiling, reported as an outcome; `launch/launch-arming.ts` (`describeLaunchArming`): what the launch has armed that could stop it soon, which picks the ceiling (30 s armed, 5 s unarmed; issue #815) and words the `pending: true` answer
      - `attach/attach-controller.ts` (`AttachController`): `attachToProcess`, `detachFromProcess`; `attach/attach-verification.ts` (`verifyAttachThreads`, `pauseAfterAttach`): the thread poll and post-attach pause that make PAUSED real before it is reported
      - `breakpoints/breakpoint-controller.ts` (`BreakpointController`): set/remove/clear plus the replace-all DAP re-sends
      - `breakpoints/anchor-resolution.ts` (`reresolveAnchors`) and `breakpoints/launch-warnings.ts` (pure warning builders)
 
@@ -0,0 +1 @@
+**`start_debugging` no longer sits out a 30 s ceiling on a launch that never stops** — for every adapter but js-debug, a launch with nothing armed to stop it (no breakpoints, no entry stop, a server or a long loop) waited the full 30 s readiness ceiling and then answered `state: "running"` with no word about the wait: those policies count only a pause as ready, and the proxy reports its configured state before the wait can listen. The wait now depends on what the launch has armed: with breakpoints (a logpoint counts when the adapter does not run it on), function breakpoints, `stopOnEntry` or `breakOnExceptions: "all"`, the first stop still gets the full ceiling, so a launch that reaches a breakpoint keeps answering `paused` with its reason; with nothing armed (the `"uncaught"` default does not count — a crash is not a stop that comes soon) the wait is a 5 s grace window. Either way, when the ceiling passes with the program still running the response says so — `pending: true` at the top level like the step tools, and a message naming what was not reached ("still running after 30s without reaching 2 breakpoint(s)") or why no stop is coming soon and what to do instead — and `restart_debugging` answers the same way. The "adapter may have failed to start" warning is logged only when the session is still initializing at the ceiling (#815)
@@ -92,6 +92,9 @@ export interface AdapterPolicy {
   getLocalScopeName?(): string | string[];
 
   // === Session readiness (optional) ===
+  // Whether a launch is reportable in this state. Every policy but js-debug answers PAUSED only,
+  // so the launcher waits for the first stop — for the full ceiling when something is armed to
+  // stop the program, for a short grace window when nothing is (issue #815; launch-arming.ts).
   isSessionReady?(state: SessionState, options: { stopOnEntry?: boolean }): boolean;
 
   // === Non-file source identifiers (optional, e.g. Java FQCNs) ===
 
@@ -314,10 +314,10 @@ startDebugging(
 
 Delegates to `DebugLauncher` (`src/session/launch/debug-launcher.ts`), which owns the launch sequence end to end.
 
-**Returns**: `DebugResult` — `{ success, state, error?, data?, canContinue?, errorType?, errorCode? }`. For a dry run, `data` carries `dryRun`, `command` and `script`. A dry run leaves the session lifecycle-TERMINATED but present; `startDebugging` accepts a present session in any lifecycle state — `DebugLauncher.launch` tears down any leftover proxy and resets the per-launch state (issue #793).
+**Returns**: `DebugResult` — `{ success, state, error?, data?, canContinue?, errorType?, errorCode? }`. For a dry run, `data` carries `dryRun`, `command` and `script`. A dry run leaves the session lifecycle-TERMINATED but present; `startDebugging` accepts a present session in any lifecycle state — `DebugLauncher.launch` tears down any leftover proxy and resets the per-launch state (issue #793). The result reflects the session after its first stop, its exit, or the readiness window (`launchReadyCeilingMs` when breakpoints, an entry stop or `breakOnExceptions: 'all'` are armed, `launchGraceMs` otherwise — `describeLaunchArming` in `launch/launch-arming.ts`); when that window passes with the program still running, `state` is `RUNNING` and `data.pending` is `true` with `data.message` saying what was or was not reached (issue #815).
 
 #### `restartDebugging(sessionId: string): Promise<DebugResult>`
-Replays the session's last real launch and re-applies breakpoints (content anchors are re-resolved). Launch-mode sessions only. Exposed as the `restart_debugging` MCP tool.
+Replays the session's last real launch and re-applies breakpoints (content anchors are re-resolved). Launch-mode sessions only. Exposed as the `restart_debugging` MCP tool. Goes through the same readiness window as `startDebugging`, so a relaunch still running when it passes answers `RUNNING` with `data.pending: true` (issue #815).
 
 #### `setBreakpoint(sessionId: string, bp: { file: string; line: number; condition?: string; logMessage?: string; suspendPolicy?: 'all' | 'thread'; requestedLine?: number; anchor?: { statement: string; nearLine?: number } }): Promise<{ breakpoint: Breakpoint; warning?: string }>`
 Sets a breakpoint in a file. Internally sends a DAP `setBreakpoints` request for all breakpoints in the same source file. `requestedLine` records the originally requested line for loud snapping; `anchor` stores the content anchor that `restartDebugging` re-resolves (issue #271); `warning` carries live-sync failures. Neither extra field ever enters the DAP payload. Accepts a session in any lifecycle state; with no live debuggee the breakpoint is stored (`verified: false`, no warning) and applied on the next launch (issue #806).
 
@@ -347,14 +347,19 @@ proxyManager.on('exit', onExit);
 **Location**: `src/session/launch/launch-readiness.ts` (`waitForLaunchReadiness`)
 
 ```typescript
-// Wait for the adapter to be configured, the first stop event, or termination.
-// Readiness can be satisfied by: stopped, adapter-configured, terminated,
-// exited, or exit. The wait never rejects — every outcome resolves, including
-// the 30s ceiling, so the caller reports whatever state the session is in
-// rather than failing a launch that is merely slow.
+// Wait for the adapter to be configured, the first stop event, termination,
+// or the ceiling. Readiness can be satisfied by: stopped, adapter-configured,
+// terminated, exited, or exit. The wait never rejects — every outcome resolves
+// with a word on how it settled ('stopped' | 'configured' | 'ended' |
+// 'ceiling' | 'already-terminal'), so the caller reports the session as it is
+// and says "still running" for a ceiling rather than failing a launch that is
+// merely slow. The ceiling is the caller's (issue #815): the full 30 s when
+// something is armed to stop the program, a short grace window when nothing
+// is — every policy but js-debug is ready only on a pause, and the real proxy
+// reports adapter-configured before this wait can listen.
 // `session.proxyManager` is re-read on every access: a terminal event handler
 // may null it while the wait is in flight.
-return new Promise<void>((resolve) => {
+return new Promise<LaunchReadinessOutcome>((resolve) => {
   let resolved = false;
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
@@ -367,18 +372,23 @@ return new Promise<void>((resolve) => {
     session.proxyManager?.removeListener('exit', handleExit);
   };
 
-  const handleStopped = () => {
-    if (!resolved) { resolved = true; cleanup(); resolve(); }
+  const settle = (outcome: LaunchReadinessOutcome, narration: string) => {
+    if (resolved) return;
+    resolved = true; cleanup();
+    ctx.logger.info(`[SessionManager] Session ${sessionId} ${narration}`);
+    resolve(outcome);
   };
+
+  const handleStopped = () => settle('stopped', 'stopped on entry');
   const handleConfigured = () => {
     // The adapter policy decides whether "configured and running" counts as
     // ready; without one, it does unless the caller asked to stop on entry.
     const readyOnRunning = policy.isSessionReady
       ? policy.isSessionReady(SessionState.RUNNING, { stopOnEntry: dapLaunchArgs?.stopOnEntry })
       : !dapLaunchArgs?.stopOnEntry;
-    if (!resolved && readyOnRunning) { resolved = true; cleanup(); resolve(); }
+    if (readyOnRunning) settle('configured', `running (stopOnEntry=${dapLaunchArgs?.stopOnEntry ?? false})`);
   };
-  // handleTerminated / handleExited / handleExit follow the same shape.
+  // handleTerminated / handleExited / handleExit settle 'ended'.
 
   // Checked BEFORE any listener is registered: the caller decided readiness
   // synchronously just before this call and nothing has been awaited since,
@@ -387,7 +397,7 @@ return new Promise<void>((resolve) => {
   const currentState = ctx.getSession(sessionId).state;
   if (currentState === SessionState.STOPPED || currentState === SessionState.ERROR) {
     resolved = true;
-    resolve();
+    resolve('already-terminal');
     return;
   }
 
@@ -397,17 +407,24 @@ return new Promise<void>((resolve) => {
   session.proxyManager?.once('exited', handleExited);
   session.proxyManager?.once('exit', handleExit);
 
-  // Ceiling after 30 seconds: log and resolve, never reject.
+  // The ceiling: a program that is running has simply not stopped — the caller
+  // answers pending: true. A session still initializing here is the adapter not
+  // answering, which is what the warning has always meant. Resolve, never reject.
   timeoutId = setTimeout(() => {
-    if (!resolved) {
-      resolved = true; cleanup();
-      ctx.logger.warn(ErrorMessages.adapterReadyTimeout(30));
-      resolve();
+    if (resolved) return;
+    resolved = true; cleanup();
+    if (session.state === SessionState.RUNNING || session.state === SessionState.PAUSED) {
+      ctx.logger.info(`[SessionManager] Session ${sessionId} still running after the ${ceilingMs / 1000}s readiness ceiling; answering with pending`);
+    } else {
+      ctx.logger.warn(ErrorMessages.adapterReadyTimeout(ceilingMs / 1000));
     }
-  }, 30000);
+    resolve('ceiling');
+  }, ceilingMs);
 });
 ```
 
+The launcher (`src/session/launch/debug-launcher.ts`) picks `ceilingMs` from `describeLaunchArming(session, stopOnEntry)` (`launch-arming.ts`): `launchReadyCeilingMs` (30 s) when line/function breakpoints, a pausing logpoint, `stopOnEntry` or `breakOnExceptions: 'all'` are armed, `launchGraceMs` (5 s) otherwise — both `SessionManagerOperations` tunables. A `'ceiling'` outcome with the session `RUNNING` becomes `data.pending: true` and `ErrorMessages.launchStillRunning(...)` on the launch response, hoisted to the top level by the `start_debugging`/`restart_debugging` handlers.
+
 ## Testing Event Patterns
 
 ### Testing Event Emissions
 
@@ -390,6 +390,12 @@ Starts debugging a script.
 }
 ```
 
+**When the launch answers:** after the adapter's handshake, `start_debugging` waits for the program's first stop, its exit, or a ceiling, and reports the session as it is at that moment (issue #815):
+
+- **A stop arrives** — `state: "paused"` with `reason` (the example above), which is why a launch with breakpoints set answers "paused at the first breakpoint" for every adapter but js-debug (js-debug counts a configured, running program as ready when no entry stop was requested, and answers `running` right away — see issue #823).
+- **The program ends first** — `state: "stopped"` with the run-to-completion summary and `exitCode` below.
+- **Neither, within the ceiling** — `state: "running"` with **`pending: true`** (top level and in `data`, like `step_over`) and a `message` that says so. The ceiling depends on what the launch has armed: with line breakpoints (a logpoint counts when the adapter does not run it on), function breakpoints, `stopOnEntry` or `breakOnExceptions: "all"`, the first stop gets 30 s and the message names what was not reached (`The program is still running after 30s without reaching 2 breakpoint(s)…`); with nothing armed — the `"uncaught"` default does not count, a crash is not a stop that comes soon — the wait is a 5 s grace window and the message says why no stop is coming (`…nothing is armed to stop it soon (no breakpoints, no entry stop, no caught-exception filter)…`) and what to do (`list_debug_sessions`, `get_output`, or set breakpoints and `restart_debugging`). A server or a long-running script therefore answers in about 5 s instead of 30. The stop, if one comes later, is reported by `list_debug_sessions` as the state flips to `paused`.
+
 **JavaScript launch configuration:** Both launch option objects accept js-debug settings;
 `adapterLaunchConfig` wins when a key appears in both. The effective `stopOnEntry` value controls
 the entry pause and is replayed by `restart_debugging`. An honoured `noDebug` disables that pause.
@@ -465,6 +471,7 @@ Restarts the debuggee in one call: terminates the current program (if still runn
 - Restart is implemented uniformly as terminate + relaunch (the DAP-spec-blessed emulation; no adapter advertises native restart), so every launch-mode language works identically. Native DAP `restart` is a possible future optimization.
 - The launch configuration is replayed verbatim (script, args, `dapLaunchArgs`, `adapterLaunchConfig`, `breakOnExceptions`); there are no per-restart overrides — call `start_debugging` for a different configuration.
 - **The output buffer starts fresh**: `outputReset: true` signals that `get_output` cursors from the previous launch are stale — read from `since: 0`.
+- The readiness wait and its `pending: true` answer are the same as `start_debugging`'s ("When the launch answers" above): a relaunch with nothing armed answers `running` after the short grace window.
 - Not available for **attach sessions** (no launch configuration to replay — detach and re-attach instead) or for sessions that were never launched, including dry-run-only sessions — call `start_debugging` on the same session instead.
 
 ---
 
@@ -39,6 +39,7 @@ Rules that prevent 90% of failed sessions:
 - **Use real frame IDs.** Take `id` from `get_stack_trace` frames; it is adapter-assigned and is not 0-indexed.
 - **Expand variable containers.** If a variable entry carries a `variablesReference`, call `get_variables` again with that reference to see children (Python's "special variables", object fields, array elements).
 - **Respect session state.** Stepping, evaluation, and variable reads require `PAUSED`. After `continue_execution` the session is `RUNNING`; after a step or breakpoint hit it returns to `PAUSED` with a persisted stop reason telling you why it stopped (`breakpoint`, `step`, `entry`, `exception`, ...).
+- **A `start_debugging` that answers `running` with `pending: true` is not stuck.** The program did not stop within the readiness window (30 s with breakpoints or an entry stop armed, 5 s with nothing armed — a server, a long loop); the message says what was or was not armed. Check `list_debug_sessions` for the state to flip to `paused`, read `get_output`, or set breakpoints and `restart_debugging`.
 - **Breakpoints may verify late.** Some adapters (debugpy, JDI) report breakpoints unverified until the module/class loads; that is normal, not an error.
 - **`<redacted:...>` placeholders are masking, not program state.** Credential-shaped values and values of sensitive variable names (`password`, `api_key`, ...) are masked by default in variable/evaluate/output results; a `redaction` field reports what was hidden. The real value is intact in the debuggee — don't "fix" it, and don't retry the read. The user can disable masking by restarting the server with `DEBUG_MCP_NO_REDACT=1`.
 - **If `get_variables` demands `names`, the server is in least-privilege mode** (`DEBUG_MCP_VARIABLE_ACCESS=explicit`): pass the exact variable names you need (`names: ["user", "total"]`; case-sensitive, misses reported in `notFound`) instead of dumping the scope. `evaluate_expression` still works for targeted reads.
 
@@ -37,6 +37,13 @@ export const startDebuggingTool: ToolHandler = async (ctx, args) => {
     if (debugResult.data) {
       responsePayload.data = debugResult.data;
     }
+    // `pending` is part of the public tool-result contract, as for the step
+    // tools (issue #144) and attach_to_process (issue #598): a launch answered
+    // while the program still runs — nothing armed stopped it within the
+    // readiness window (issue #815) — is visible at the top level.
+    if (debugResult.data?.pending) {
+      responsePayload.pending = true;
+    }
     // Top-level warning join (set_breakpoint pattern): intake
     // normalization notes (issue #305) plus any session-manager
     // warning (unbound function breakpoints, issue #308).
@@ -74,6 +81,11 @@ export const restartDebuggingTool: ToolHandler = async (ctx, args) => {
       if (restartWarning) {
         responsePayload.warning = restartWarning;
       }
+      // A relaunch that is still running at the readiness ceiling (issue
+      // #815): same top-level pending as start_debugging.
+      if (debugResult.data.pending) {
+        responsePayload.pending = true;
+      }
     }
     return jsonResult(responsePayload);
   } catch (error) {
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`start_debugging` no longer sits out a 30 s ceiling on a launch that never stops — for every adapter but js-debug, a launch with nothing armed to stop it (no breakpoints, no entry stop, a server or a long loop) waited the full 30 s readiness ceiling and then answered `state: "running"` with no word about the wait: those policies count only a pause as ready, and the proxy reports its configured state before the wait can listen. The wait now depends on what the launch has armed: with breakpoints (a logpoint counts when the adapter does not run it on), function breakpoints, `stopOnEntry` or `breakOnExceptions: "all"`, the first stop still gets the full ceiling, so a launch that reaches a breakpoint keeps answering `paused` with its reason; with nothing armed (the `"uncaught"` default does not count — a crash is not a stop that comes soon) the wait is a 5 s grace window. Either way, when the ceiling passes with the program still running the response says so — `pending: true` at the top level like the step tools, and a message naming what was not reached ("still running after 30s without reaching 2 breakpoint(s)") or why no stop is coming soon and what to do instead — and `restart_debugging` answers the same way. The "adapter may have failed to start" warning is logged only when the session is still initializing at the ceiling (#815)