fix(javascript): catch the first call of a first-declared function breakpoint and explain a late entry stop (#858)

js-debug's stopOnEntry breakpoint sits at line 0 col 0 and V8 resolves it
to the first breakable position in source order — the body of a function
declared above the first statement — so the "entry" stop is that
function's first call and recurs at every later call
(microsoft/vscode-js-debug#2430). The forced entry stop that binds a
pre-launch function breakpoint was that first call, auto-continued and
lost. The CDP bridge now reports an entry stop whose paused frame is the
function it just armed (matched by [[FunctionLocation]]) as the function
breakpoint, and annotates an entry stop that landed inside a function in
the stopped event's text; ChildSessionManager routes entry stops to the
bridge with nothing armed. The adapter's inert --inspect-brk=9229 append
and its --inspect promotion are removed (js-debug strips --inspect-brk
into stopOnEntry itself).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: cynarlab

changelog.d/858-js-entry-stop.fixed.md

@@ -0,0 +1 @@
+**A JavaScript function breakpoint on the first-declared function no longer misses its first call, and a late entry stop says where it landed** — js-debug implements `stopOnEntry` with a breakpoint at line 1, column 1 that V8 resolves to the first breakable position in source order: for a file whose first declaration is a function the program calls later, that is the function's body, so the "entry" stop fires at the function's first call (after the top-level code before it ran) and again at every later call. The forced entry stop that binds a pre-launch function breakpoint was that very first call, and auto-continuing it lost the call for good with the breakpoint listed `verified: true`. The CDP bridge now recognises an entry stop whose paused frame is the function it just armed — matched by `[[FunctionLocation]]`, never by name — and reports it as the function breakpoint. A `stopOnEntry` launch that lands inside a function carries the explanation in the stop's `text` (`start_debugging`, `wait_for_stop`, `list_debug_sessions`): where it stopped, why, that the code before it has run, that later calls stop again, and what to do instead. The JavaScript adapter also stops appending `--inspect-brk=9229` to `runtimeArgs` for `stopOnEntry` and promoting a user's `--inspect` to `--inspect-brk` — js-debug strips `--inspect-brk` into `stopOnEntry` itself, so the first was inert and the second forced an entry stop nobody asked for. Reported upstream as microsoft/vscode-js-debug#2430 (#858)

docs/javascript/README.md

@@ -158,6 +158,19 @@ Both `dapLaunchArgs` and `adapterLaunchConfig` accept launch settings. When the
 in both, `adapterLaunchConfig` wins, including `stopOnEntry`. Setting it to `true` keeps the target
 paused at entry; `restart_debugging` replays that intent. An honoured `noDebug` disables the entry pause.
 
+**Where the entry stop lands** (issue #858): js-debug implements `stopOnEntry` with a breakpoint at line 1,
+column 1 of the program, and V8 resolves that to the first breakable position in *source* order. For a file
+whose first declaration is a function that the program calls later, that position is inside the function —
+so the "entry" stop fires at the function's first call, after the top-level code before it has run (output
+included), and fires again at every later call. mcp-debugger cannot move the stop, but it says so: the
+stop's `lastStop.text` (in the `start_debugging` answer, `wait_for_stop`, `list_debug_sessions`) explains
+where it landed and why. To stop at the first statement, put a statement above the function or set a line
+breakpoint on it. A function breakpoint on that first-declared function is not affected: the stop that
+binds it *is* the function's first call, and it is reported as the function breakpoint. Reported upstream as
+[vscode-js-debug#2430](https://github.com/microsoft/vscode-js-debug/issues/2430). Node's `--inspect-brk` is not an alternative: js-debug strips it from `runtimeArgs`
+into `stopOnEntry`, so a bare `--inspect` or `--inspect-brk` in `adapterLaunchConfig.runtimeArgs` is
+forwarded as given and changes nothing about the entry stop.
+
 Use `envFile` to load dotenv values relative to the effective `cwd`, then override individual values
 with `env`. A `null` value removes an inherited or file-defined variable:
 

examples/javascript/function_first.js

@@ -0,0 +1,11 @@
+// A file whose first declaration is a function the program calls later. For
+// such a file js-debug's stopOnEntry breakpoint (line 1, column 1) is resolved
+// by V8 to the first breakable position in SOURCE order — inside work() — so
+// the "entry" stop is really work's first call (issue #858). Drives the
+// function-breakpoint and stopOnEntry e2e cases for that issue.
+function work(base) {
+  const total = base + 1; // WORK_ENTRY_LINE
+  return total;
+}
+console.log('started');
+setTimeout(() => console.log('late total', work(41)), 1500);

packages/adapter-javascript/src/javascript-debug-adapter.ts

@@ -737,45 +737,18 @@ export class JavascriptDebugAdapter extends EventEmitter implements IDebugAdapte
       }
     }
 
-    // Append any user-provided args last and normalize/dedupe
-    let finalArgs = this.normalizeAndDedupeArgs([...computedArgs, ...userRuntimeArgs]);
-
-    // Normalize Node inspector flags: ensure explicit port form, and add --inspect-brk when stopOnEntry is true
+    // Append any user-provided args last and normalize/dedupe. Node inspector
+    // flags pass through as given: js-debug itself strips an --inspect-brk out
+    // of runtimeArgs into stopOnEntry (its resolveParams), so the
+    // --inspect-brk=9229 this transform used to append for stopOnEntry was
+    // inert, and promoting a user's bare --inspect to --inspect-brk forced an
+    // entry stop nobody asked for (issue #858).
+    const finalArgs = this.normalizeAndDedupeArgs([...computedArgs, ...userRuntimeArgs]);
 
     result.runtimeExecutable = runtimeExecutableSync;
     if (finalArgs.length > 0) {
       result.runtimeArgs = finalArgs;
     }
-    // Normalize Node inspector flags for js-debug.
-    // If an --inspect/--inspect-brk flag is present, ensure it includes an explicit port.
-    if (isNodeRuntime) {
-      const findInspectIndex = () =>
-        finalArgs.findIndex(
-          (a) =>
-            a === '--inspect' ||
-            a === '--inspect-brk' ||
-            a.startsWith('--inspect=') ||
-            a.startsWith('--inspect-brk=')
-        );
-      const idx = findInspectIndex();
-      if (idx !== -1) {
-        const port = 9229;
-        const arg = finalArgs[idx];
-        const m = arg.match(/^--inspect(?:-brk)?=(\d+)$/);
-        if (m) {
-          // Port is already explicit in the flag; no rewrite needed
-        } else {
-          // Promote to explicit port for consistency and reliable auto-attach
-          finalArgs[idx] = `--inspect-brk=${port}`;
-          result.runtimeArgs = finalArgs;
-        }
-      } else if (stopOnEntry === true) {
-        // Ensure a deterministic single-session stop on entry when requested
-        const port = 9229;
-        finalArgs = [...finalArgs, `--inspect-brk=${port}`];
-        result.runtimeArgs = finalArgs;
-      }
-    }
 
     // Forward every js-debug key the caller passed that this transform does
     // not derive — trace, perScriptSourcemaps, timeouts, sourceMapPathOverrides,

packages/adapter-javascript/tests/unit/javascript-debug-adapter.transform.test.ts

@@ -211,6 +211,21 @@ describe('JavascriptDebugAdapter.transformLaunchConfig', () => {
     expect(ra[ra.length - 1]).toBe('--my-flag');
   });
 
+  it('does not add or rewrite Node inspector flags: stopOnEntry is js-debug\'s, and a user --inspect is forwarded as given (issue #858)', async () => {
+    // js-debug strips any --inspect-brk from runtimeArgs into stopOnEntry
+    // (vendored bundle, resolveParams), so the --inspect-brk=9229 the
+    // transform used to append was inert — and promoting a user's --inspect
+    // to --inspect-brk forced an entry stop nobody asked for.
+    const program = path.resolve('/proj/app.js');
+    const withEntry = await adapter.transformLaunchConfig({ program, stopOnEntry: true } as any);
+    expect(withEntry.stopOnEntry).toBe(true);
+    expect(((withEntry.runtimeArgs ?? []) as string[]).some((a) => a.startsWith('--inspect'))).toBe(false);
+
+    const withInspect = await adapter.transformLaunchConfig({ program, stopOnEntry: false, runtimeArgs: ['--inspect'] } as any);
+    expect(withInspect.runtimeArgs).toEqual(['--inspect']);
+    expect(withInspect.stopOnEntry).toBe(false);
+  });
+
   it('runtimeExecutable override: "tsx" results in empty hooks', async () => {
     const program = path.resolve('/proj/app.ts');
     const cfg = await adapter.transformLaunchConfig({

skills/debugging/references/javascript.md

@@ -68,7 +68,7 @@ Shorthand: `create_debug_session { "language": "javascript", "host": "127.0.0.1"
 ## Quirks
 
 - **Child-session architecture.** js-debug runs a parent session for launch orchestration and spawns a child session for the actual debuggee. This is invisible to you: the proxy routes evaluate/step/stack commands to the active context automatically. Never create a second MCP session for the "other" half.
-- **Entry pause auto-continues.** With `stopOnEntry: false` (the default) the debugger automatically continues past entry breakpoints, so execution runs straight to your first breakpoint. A breakpoint reached as the program starts is in the `start_debugging` answer; one reached later — a route handler, a timer — leaves the launch answering `pending: true`, and `wait_for_stop` collects it. Set `dapLaunchArgs: { "stopOnEntry": true }` only when you want control at the first line.
+- **Entry pause auto-continues.** With `stopOnEntry: false` (the default) the debugger automatically continues past entry breakpoints, so execution runs straight to your first breakpoint. A breakpoint reached as the program starts is in the `start_debugging` answer; one reached later — a route handler, a timer — leaves the launch answering `pending: true`, and `wait_for_stop` collects it. Set `dapLaunchArgs: { "stopOnEntry": true }` only when you want control at the first line — and read `lastStop.text` when you get it: for a file whose first declaration is a function the program calls later, js-debug's entry breakpoint resolves *inside that function*, so the "entry" stop is its first call (top-level code before it has already run) and every later call stops as "entry" again. The text says so; a line breakpoint on the first statement is the reliable way to stop there.
 - **Stack filtering hides Node internals.** `get_stack_trace` returns user frames only by default; pass `includeInternals: true` if you genuinely need Node.js internal frames. If execution initially stops inside internals, just `continue_execution`.
 - **TypeScript auto-detection.** Point `scriptPath` at the `.ts` file when `tsx`/`ts-node` is available. If neither is installed you get a warning (not an error) — fall back to the compiled `.js` with source maps.
 - **Child processes are not auto-attached.** `autoAttachChildProcesses` defaults to `false`; pass it as `true` in `dapLaunchArgs` to debug `spawn`-ed Node children.

src/proxy/cdp-function-breakpoint-bridge.ts

@@ -1081,7 +1081,10 @@ export class ChildSessionManager extends EventEmitter {
         await this.bridgeAttachSettled;
         let out = evt;
         if (evt.event === 'stopped') {
-          if (bridge.hasArmedOrPending()) {
+          // An entry stop always goes through the bridge: with nothing armed
+          // it can still be a late entry inside a function (issue #858).
+          const reason = (evt.body as { reason?: string } | undefined)?.reason;
+          if (bridge.hasArmedOrPending() || reason === 'entry') {
             try {
               out = await bridge.processStoppedEvent(evt);
             } catch (err) {

src/proxy/child-session-manager.ts

@@ -33,6 +33,9 @@ const __dirname = path.dirname(__filename);
 const ROOT = path.resolve(__dirname, '../..');
 const FIXTURE = path.resolve(ROOT, 'examples', 'javascript', 'function_bp_test.js');
 const ATTACH_TARGET = path.resolve(ROOT, 'examples', 'javascript', 'function_bp_attach_target.js');
+// A function declared above the first statement and called 1.5 s in (issue #858)
+const FUNCTION_FIRST = path.resolve(ROOT, 'examples', 'javascript', 'function_first.js');
+const WORK_ENTRY_LINE = 7;
 
 const COMPUTE_DECL_LINE = 9;
 const COMPUTE_ENTRY_LINE = 10;
@@ -197,6 +200,50 @@ describe('MCP Server JavaScript Function Breakpoints', () => {
     expect(contRes.success).toBe(true);
   }, 60000);
 
+  it('catches the first call of a function declared above the first statement (issue #858)', async () => {
+    // js-debug's entry breakpoint resolves into work's body, so the forced
+    // entry stop that binds the function breakpoint IS work's first call —
+    // before this fix that stop was auto-continued and the only call was lost.
+    const sid = await createSession('js-fnbp-function-first');
+    const bpRes = await callToolSafely(mcpClient!, 'set_breakpoint', { sessionId: sid, function: 'work' });
+    expect(bpRes.success).toBe(true);
+
+    const startResponse = parseSdkToolResult(await mcpClient!.callTool({
+      name: 'start_debugging',
+      arguments: { sessionId: sid, scriptPath: FUNCTION_FIRST, dapLaunchArgs: { stopOnEntry: false } }
+    }));
+    expect(startResponse.state).toBeDefined();
+
+    const stack = await waitForPausedState(sid);
+    expect(stack, 'the only call of work() ran to completion without stopping').not.toBeNull();
+    const top = stack!.stackFrames![0];
+    expect(top.name).toContain('work');
+    expect(top.line).toBe(WORK_ENTRY_LINE);
+    expect((await getSessionSnapshot(sid))?.lastStop?.reason).toBe('function breakpoint');
+    const output = await callToolSafely(mcpClient!, 'get_output', { sessionId: sid, since: 0 });
+    const text = JSON.stringify((output as { entries?: unknown[] }).entries ?? []);
+    expect(text).toContain('started');
+    expect(text).not.toContain('late total');
+
+    await callToolSafely(mcpClient!, 'continue_execution', { sessionId: sid });
+  }, 60000);
+
+  it('says so when a stopOnEntry launch stops inside a function instead of at the first statement (issue #858)', async () => {
+    const sid = await createSession('js-late-entry');
+    const startResponse = parseSdkToolResult(await mcpClient!.callTool({
+      name: 'start_debugging',
+      arguments: { sessionId: sid, scriptPath: FUNCTION_FIRST, dapLaunchArgs: { stopOnEntry: true } }
+    })) as { state?: string; data?: { reason?: string } };
+    expect(startResponse.state).toBe('paused');
+    expect(startResponse.data?.reason).toBe('entry');
+
+    const snapshot = await getSessionSnapshot(sid) as { lastStop?: { reason?: string; text?: string } } | undefined;
+    expect(snapshot?.lastStop?.reason).toBe('entry');
+    expect(snapshot?.lastStop?.text).toMatch(/entry stop landed inside work\(\) at its first call/);
+    const stack = await waitForPausedState(sid);
+    expect(stack!.stackFrames![0].name).toContain('work');
+  }, 60000);
+
   it('defers a lazily-loaded module function until a pause after the require, then binds and stops', async () => {
     const sid = await createSession('js-fnbp-deferred');
 

tests/e2e/mcp-server-smoke-js-function-bp.test.ts

@@ -88,14 +88,22 @@ class FakeCdpClient extends EventEmitter {
     return this.calls.filter((c) => c.method === method);
   }
 
-  pause(opts: { hitBreakpoints?: string[]; callFrameId?: string; scriptId?: string; url?: string } = {}): void {
+  pause(opts: {
+    hitBreakpoints?: string[];
+    callFrameId?: string;
+    scriptId?: string;
+    url?: string;
+    functionName?: string;
+    functionLocation?: { scriptId: string; lineNumber: number; columnNumber: number };
+  } = {}): void {
     this.emit('cdp-event', 'Debugger.paused', {
       reason: 'other',
       hitBreakpoints: opts.hitBreakpoints ?? [],
       callFrames: [
         {
           callFrameId: opts.callFrameId ?? 'frame-1',
-          functionName: '',
+          functionName: opts.functionName ?? '',
+          ...(opts.functionLocation ? { functionLocation: opts.functionLocation } : {}),
           location: { scriptId: opts.scriptId ?? '159', lineNumber: 0, columnNumber: 0 },
           url: opts.url ?? ''
         }
@@ -482,6 +490,58 @@ describe('CdpFunctionBreakpointBridge', () => {
     });
   });
 
+  describe('late entry stops (issue #858)', () => {
+    // js-debug sets its stopOnEntry breakpoint at line 1 col 1 and V8 resolves
+    // it to the first breakable position in source order — inside a function
+    // declared above the first statement — so the "entry" stop is really that
+    // function's first call.
+    const WORK_LOCATION = { scriptId: '159', lineNumber: 2, columnNumber: 14 }; // the fake's [[FunctionLocation]]
+
+    it('relabels an entry stop that lands inside the function just armed as that function breakpoint', async () => {
+      cdp.frameFunctions.set('work', 'obj-work');
+      const body = await bridge.sync([fnBp('work')]);
+      const adapterId = body.breakpoints[0].id!;
+      await attach();
+
+      // js-debug's own entry breakpoint id is foreign to us; the frame is work's body
+      cdp.pause({ hitBreakpoints: ['js-debug-entry-bp'], functionName: 'work', functionLocation: WORK_LOCATION });
+      await bridge.waitForResolution();
+      const out = await bridge.processStoppedEvent(stoppedEvent('entry'));
+      const stopped = out.body as DebugProtocol.StoppedEvent['body'];
+      expect(stopped.reason).toBe('function breakpoint');
+      expect(stopped.hitBreakpointIds).toEqual([adapterId]);
+    });
+
+    it('leaves an entry stop inside some other function to the note path (no false relabel by name)', async () => {
+      cdp.frameFunctions.set('work', 'obj-work');
+      await bridge.sync([fnBp('work')]);
+      await attach();
+      cdp.pause({ hitBreakpoints: ['js-debug-entry-bp'], functionName: 'work', functionLocation: { scriptId: '159', lineNumber: 40, columnNumber: 9 } });
+      await bridge.waitForResolution();
+      const out = await bridge.processStoppedEvent(stoppedEvent('entry'));
+      const stopped = out.body as DebugProtocol.StoppedEvent['body'];
+      expect(stopped.reason).toBe('entry');
+      expect(stopped.text).toMatch(/entry stop landed inside work\(\)/);
+    });
+
+    it('annotates a late entry stop with no function breakpoints at all, and leaves a top-level entry stop alone', async () => {
+      await attach();
+      expect(bridge.hasArmedOrPending()).toBe(false);
+
+      cdp.pause({ hitBreakpoints: ['js-debug-entry-bp'], functionName: 'helper', functionLocation: { scriptId: '159', lineNumber: 0, columnNumber: 15 } });
+      const late = await bridge.processStoppedEvent(stoppedEvent('entry'));
+      const lateBody = late.body as DebugProtocol.StoppedEvent['body'];
+      expect(lateBody.reason).toBe('entry');
+      expect(lateBody.text).toMatch(/entry stop landed inside helper\(\) at its first call/);
+      expect(lateBody.text).toMatch(/every later call of helper\(\) stops as "entry" again/);
+
+      cdp.resume();
+      cdp.pause({ hitBreakpoints: ['js-debug-entry-bp'], functionName: '' });
+      const top = await bridge.processStoppedEvent(stoppedEvent('entry'));
+      expect((top.body as DebugProtocol.StoppedEvent['body']).text).toBeUndefined();
+    });
+  });
+
   describe('deferred binding', () => {
     it('re-resolves pending names at each pause and emits changed on late bind', async () => {
       await bridge.sync([fnBp('helper.doWork')]);