fix(docker): ship the JavaScript exit-code shim in the image and test exit codes end to end (#796, #735) (#809)

JavaScript programs ran fine in the Docker image but their sessions ended stopped with no exitCode. js-debug never sends a DAP exited event; the code comes from a preload the adapter injects (assets/exitcode-shim.cjs, #247) and the adapter degraded silently without it. The Dockerfile re-materialised the adapter from dist, vendor and package.json only, so assets/ never reached the image (measured: the local images hold dist package.json vendor and nothing else).

The image now copies the adapter's assets and fails to build if the shim is missing (the same guard the CodeLLDB engine has, #387); the npm bundle build fails without it too (bundle-cli.js throws instead of warning); a JavaScript launch that cannot find the preload says so in its start_debugging warning through a new launch-scoped diagnostic (LaunchConfigDiagnostic.scope 'launch', rendered as-is by the launcher, whose existing rendering matches diagnostics against caller keys only); a Docker smoke case waits for the exit code itself (7) in debug mode and under noDebug on the new examples/javascript/exit_code_test.js; and the CI-run JavaScript integration file gains a debugger-on run-to-completion case asserting exitCode 7 in list_debug_sessions (and on the summary when the fixture beats launch readiness) — #735 item 4, where #794's case covered noDebug only.

Closes #796
Refs #735

Review and verification:
- Multi-agent code review: no correctness defects, 5 altitude findings; 4 fixed (the bundle gate moved from the never-run test-bundle.cjs into bundle-cli.js; the missing-shim launch notice; pollUntil in the Docker test; a race-honest description of the summary assertion), 1 deferred to #811 (re-materialise adapter packages from their package.json files field). The notice change surfaced three #709 diagnostics tests whose harness had no file system; they now model the preload as present.
- Local: the rebuilt image contains the shim and passes the guard; Docker JS smoke 8/8 including both new cases; JS integration file 11/11 on the merged tree; unit and launcher suites green; pre-push (6402 unit, 92 integration) and CI green on both OSes including Container Tests.

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

Author: debugmcpdev

Dockerfile

@@ -138,6 +138,7 @@ RUN rm -rf /app/node_modules/@debugmcp && \
     cp /app/packages/adapter-python/package.json /app/node_modules/@debugmcp/adapter-python/ && \
     cp -r /app/packages/adapter-javascript/dist /app/node_modules/@debugmcp/adapter-javascript/ && \
     cp -r /app/packages/adapter-javascript/vendor /app/node_modules/@debugmcp/adapter-javascript/ && \
+    cp -r /app/packages/adapter-javascript/assets /app/node_modules/@debugmcp/adapter-javascript/ && \
     cp /app/packages/adapter-javascript/package.json /app/node_modules/@debugmcp/adapter-javascript/ && \
     mkdir -p /app/node_modules/@debugmcp/adapter-javascript/node_modules && \
     cp -rL /app/packages/adapter-javascript/node_modules/dotenv /app/node_modules/@debugmcp/adapter-javascript/node_modules/ && \
@@ -272,6 +273,11 @@ COPY --from=builder /app/node_modules/.pnpm/isexe@4.0.0/node_modules/isexe /app/
 # runtime dependency copy is incomplete, instead of shipping a broken launch.
 RUN node --input-type=module -e "await import('@debugmcp/adapter-javascript')"
 
+# The JavaScript adapter's exit-code preload (issue #796): js-debug never
+# sends a DAP exited event, so exitCode comes from this shim, which the
+# adapter degrades silently without. Fail the build if the copy is missing.
+RUN test -f /app/node_modules/@debugmcp/adapter-javascript/assets/exitcode-shim.cjs
+
 # Expose ports
 EXPOSE 3001 5679
 

changelog.d/796.fixed.md

@@ -0,0 +1 @@
+**Docker JavaScript launches report `exitCode` again** — the image copied the JavaScript adapter's `dist`, `vendor` and `package.json` but not its `assets/`, so `exitcode-shim.cjs` (the preload that records the debuggee's exit code, since js-debug never sends `exited`) was missing and every JavaScript session in the container ended `stopped` with no `exitCode`. The image now ships the asset and fails to build without it (the same guard the CodeLLDB engine has), the npm bundle build fails without it too, a JavaScript launch that cannot find the preload says so in its `warning` instead of only in the server log, and the Docker smoke test waits for the non-zero exit code itself, in debug and noDebug mode (#796)

examples/javascript/exit_code_test.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Exit-code fixture for MCP debugger smoke tests.
+ *
+ * Prints one line and exits with status 7, so a test can tell "the program
+ * ran to completion" from "the debugger reported its exit code" (issue #796:
+ * the Docker image shipped without the JavaScript exit-code preload, and
+ * sessions ended `stopped` with no exitCode at all).
+ */
+console.log('exit_code_test: exiting with status 7');
+process.exitCode = 7;

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

@@ -922,9 +922,11 @@ export class JavascriptDebugAdapter extends EventEmitter implements IDebugAdapte
     }
 
     if (!shimPath) {
-      this.dependencies.logger?.warn?.(
-        '[JavascriptDebugAdapter] exitcode-shim.cjs not found; debuggee exit code will not be captured'
-      );
+      // Not a caller key: a launch-scoped notice the launcher renders as-is, so
+      // the first launch says it instead of the server log alone (issue #796).
+      const message = `exit codes will not be captured: exitcode-shim.cjs not found (looked in ${candidates.join(', ')})`;
+      this.dependencies.logger?.warn?.(`[JavascriptDebugAdapter] ${message}`);
+      this.launchConfigDiagnostics.push({ key: 'exitcode-shim.cjs', scope: 'launch', message });
       return;
     }
 

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

@@ -332,6 +332,27 @@ describe('JavascriptDebugAdapter.transformLaunchConfig', () => {
       expect(requireArg).not.toContain('\\');
     });
 
+    it('reports a missing shim as a launch notice instead of degrading silently (issue #796)', async () => {
+      const withoutShim = new JavascriptDebugAdapter({
+        ...deps,
+        fileSystem: { existsSync: () => false }
+      } as unknown as import('@debugmcp/shared').AdapterDependencies);
+      const cfg = await withoutShim.transformLaunchConfig({
+        program: path.resolve('/proj/app.js')
+      } as any);
+
+      const env = cfg.env as Record<string, string>;
+      expect(env.MCP_DEBUGGER_EXITCODE_FILE).toBeUndefined();
+      expect(env.NODE_OPTIONS ?? '').not.toContain('exitcode-shim');
+      expect(withoutShim.consumeLaunchConfigDiagnostics()).toContainEqual(
+        expect.objectContaining({
+          key: 'exitcode-shim.cjs',
+          scope: 'launch',
+          message: expect.stringContaining('exit codes will not be captured: exitcode-shim.cjs not found')
+        })
+      );
+    });
+
     it('preserves pre-existing NODE_OPTIONS content', async () => {
       const withFs = new JavascriptDebugAdapter(depsWithFs);
       const cfg = await withFs.transformLaunchConfig({

packages/adapter-javascript/tests/unit/launch-config-diagnostics.test.ts

@@ -2,8 +2,12 @@ import { describe, expect, it, vi } from 'vitest';
 import type { AdapterDependencies, GenericLaunchConfig } from '@debugmcp/shared';
 import { JavascriptDebugAdapter } from '../../src/javascript-debug-adapter.js';
 
+// The exit-code preload resolves through fileSystem.existsSync; a harness
+// without one would carry the missing-shim launch notice on every transform (#796).
+const shimPresent = { existsSync: () => true };
+
 function adapter() {
-  return new JavascriptDebugAdapter({ logger: { info: vi.fn(), warn: vi.fn() } } as unknown as AdapterDependencies);
+  return new JavascriptDebugAdapter({ logger: { info: vi.fn(), warn: vi.fn() }, fileSystem: shimPresent } as unknown as AdapterDependencies);
 }
 
 describe('JavaScript launch diagnostics (#709)', () => {
@@ -27,7 +31,7 @@ describe('JavaScript launch diagnostics (#709)', () => {
 
   it('accepts explicit empty lists, null source-map locations and matching pinned values', async () => {
     const logger = { info: vi.fn(), warn: vi.fn() };
-    const subject = new JavascriptDebugAdapter({ logger } as unknown as AdapterDependencies);
+    const subject = new JavascriptDebugAdapter({ logger, fileSystem: shimPresent } as unknown as AdapterDependencies);
     const result = await subject.transformLaunchConfig({ program: '/project/app.js', outFiles: [], skipFiles: [],
       runtimeArgs: [], resolveSourceMapLocations: null, console: 'internalConsole', type: 'pwa-node', envFile: null,
       request: 'launch'
@@ -57,7 +61,7 @@ describe('JavaScript launch diagnostics (#709)', () => {
 
   it('consumes envFile and keeps null env entries in the DAP result', async () => {
     const subject = new JavascriptDebugAdapter({
-      logger: { info: vi.fn(), warn: vi.fn() }, fileSystem: { readFile: vi.fn(async () => 'REMOVE=file\nFILE_ONLY=works\n') }
+      logger: { info: vi.fn(), warn: vi.fn() }, fileSystem: { ...shimPresent, readFile: vi.fn(async () => 'REMOVE=file\nFILE_ONLY=works\n') }
     } as unknown as AdapterDependencies);
     const result = await subject.transformLaunchConfig({ program: '/project/app.js', envFile: 'app.env', env: { REMOVE: null } } as GenericLaunchConfig);
     expect(result.env).toMatchObject({ REMOVE: null, FILE_ONLY: 'works' });

packages/mcp-debugger/scripts/bundle-cli.js

@@ -274,7 +274,9 @@ async function bundleCLI() {
     fs.copyFileSync(exitShimSrc, path.join(assetsDest, 'exitcode-shim.cjs'));
     console.log('Copied exitcode-shim.cjs.');
   } else {
-    console.warn('Warning: exitcode-shim.cjs not found; JS debuggee exit codes will not be captured in NPX distribution.');
+    // Fail the bundle rather than ship a package whose JavaScript sessions end
+    // with no exitCode (issue #796, the same class the Docker image had).
+    throw new Error(`exitcode-shim.cjs not found at ${exitShimSrc}; the npm bundle must ship the JavaScript exit-code preload (issue #796)`);
   }
 
   // Copy the agent skill so the package is a pi coding-agent package (issue

packages/shared/src/interfaces/debug-adapter.ts

@@ -404,8 +404,16 @@ export interface GenericLaunchConfig {
 
 /** An adapter's explanation of how it handled one launch input. */
 export interface LaunchConfigDiagnostic {
+  /** The caller's launch key this is about — or, with scope 'launch', a label for a notice about the launch as a whole. */
   key: string;
   message: string;
+  /**
+   * 'launch': not tied to a caller input. The launcher renders the message
+   * as-is instead of matching `key` against the caller's keys (issue #796 —
+   * e.g. the JavaScript adapter's exit-code preload is missing from this
+   * distribution, so exit codes will not be captured).
+   */
+  scope?: 'launch';
 }
 
 /**

src/session/launch/launch-config-diagnostics.ts

@@ -50,5 +50,9 @@ export function collectLaunchConfigNotices(
       notices.push(`${name}: ${message}${suggestion && suggestion !== key ? ` (did you mean ${suggestion}?)` : ''}`);
     }
   }
+  // Launch-scoped notices are about the launch as a whole, not a caller key (#796).
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.scope === 'launch') notices.push(diagnostic.message);
+  }
   return [...new Set(notices)];
 }

tests/core/unit/session/launch/launch-config-diagnostics.test.ts

@@ -0,0 +1,33 @@
+/**
+ * collectLaunchConfigNotices turns the adapter's per-key diagnostics into the
+ * start_debugging warning by matching them against the caller's launch keys.
+ * A scope: 'launch' diagnostic is about the launch as a whole (issue #796) and
+ * must reach the warning with no caller key to match.
+ */
+import { describe, it, expect } from 'vitest';
+import type { IDebugAdapter, LanguageSpecificLaunchConfig } from '@debugmcp/shared';
+import { collectLaunchConfigNotices } from '../../../../../src/session/launch/launch-config-diagnostics.js';
+
+describe('collectLaunchConfigNotices — launch-scoped diagnostics (issue #796)', () => {
+  it('renders a scope: launch diagnostic as-is even though no caller key matches it', () => {
+    const adapter = {
+      supportedLaunchKeys: ['program'],
+      consumeLaunchConfigDiagnostics: () => [
+        { key: 'exitcode-shim.cjs', scope: 'launch' as const, message: 'exit codes will not be captured: exitcode-shim.cjs not found (looked in /a, /b)' }
+      ]
+    } as unknown as IDebugAdapter;
+
+    const notices = collectLaunchConfigNotices(adapter, {}, { program: '/app.js' } as LanguageSpecificLaunchConfig);
+
+    expect(notices).toEqual(['exit codes will not be captured: exitcode-shim.cjs not found (looked in /a, /b)']);
+  });
+
+  it('still matches ordinary diagnostics on the caller key only', () => {
+    const adapter = {
+      supportedLaunchKeys: ['program'],
+      consumeLaunchConfigDiagnostics: () => [{ key: 'runtimeArgs', message: 'expected an array of strings' }]
+    } as unknown as IDebugAdapter;
+
+    expect(collectLaunchConfigNotices(adapter, {}, { program: '/app.js' } as LanguageSpecificLaunchConfig)).toEqual([]);
+  });
+});