@@ -94,6 +94,23 @@ Data breakpoints (hardware watchpoints), disassembly view, instruction stepping,
 - The launch default `"uncaught"` sets **no filter**: LLDB has no uncaught-only C++ filter, and an uncaught exception reaches `std::terminate` → SIGABRT, which the debugger stops on natively — you still land at the crash with stack and locals.
 - `cpp_catch` (break on catch) is available via explicit filter configuration.
 
+## Debugging host-built binaries in Docker
+
+A binary compiled on the host embeds host-absolute source paths (e.g. `/home/user/proj/src/main.cpp`) in its DWARF debug info. When the mcp-debugger container mounts the project at `/workspace`, breakpoint requests use `/workspace/...` paths and CodeLLDB cannot match them against the DWARF paths — file+line breakpoints and logpoints silently never bind (function breakpoints and pause still work; issue #363).
+
+In container mode (`MCP_CONTAINER=true`) the adapter auto-derives a best-effort `sourceMap` for prebuilt binaries by scanning the binary for embedded host paths whose suffixes exist under the workspace mount (`MCP_WORKSPACE_ROOT`, default `/workspace`), so this usually just works. If auto-derivation misses (unusual layouts, stripped path strings), pass the mapping explicitly — a caller-supplied `sourceMap` always wins:
+
+```json
+{
+  "scriptPath": "/workspace/build/app",
+  "dapLaunchArgs": {
+    "sourceMap": { "/home/user/proj": "/workspace" }
+  }
+}
+```
+
+Alternatively, compile inside the container (or with `-fdebug-prefix-map=/home/user/proj=/workspace`) so the DWARF paths match the mount directly.
+
 ## Troubleshooting
 
 - **"CodeLLDB executable not found"** — run `pnpm --filter @debugmcp/codelldb-common run build:adapter`, or set `CODELLDB_PATH`.
 
@@ -187,6 +187,35 @@ Breakpoints, conditional breakpoints, locals, and expression evaluation all work
 the pod exactly as they do locally. For a pod on a real cluster, the only difference is
 where `kubectl port-forward` points.
 
+### Attaching across a container boundary
+
+Attach sessions send breakpoint paths to the remote rdbg **verbatim** — rdbg checks them
+against the debug **target's** filesystem, not yours. When the debugger and the debuggee
+see the project at different paths (host mcp-debugger + containerized app, or a
+containerized mcp-debugger + host app), a path that is valid on your side can fail on the
+target with `<path> is not available`. That warning is topology, not breakage:
+
+- **Prefer target-side paths.** Set breakpoints using the path the debuggee sees
+  (`/app/app.rb` inside the container, as reported by `get_stack_trace`), not the path on
+  your machine.
+- **Or map paths with `localfsMap`.** rdbg accepts a `localfsMap` attach option
+  (`"remote_prefix:local_prefix"`, comma-separated for multiple pairs) that translates
+  paths between the two filesystems. Pass it through `attach_to_process`:
+
+  ```text
+  attach_to_process {
+    "sessionId": "...",
+    "host": "127.0.0.1",
+    "port": 12345,
+    "localfsMap": "/app:/home/user/project"
+  }
+  ```
+
+- **Reaching a host-side rdbg from a containerized mcp-debugger:** use
+  `host.docker.internal` as the attach host (add
+  `--add-host=host.docker.internal:host-gateway` on Linux Docker), and remember the
+  target-side rule still applies — the host rdbg needs host paths.
+
 ## Troubleshooting
 
 | Symptom | Likely cause / fix |
 
@@ -291,6 +291,23 @@ Response will show Rust types clearly:
 }
 ```
 
+## Debugging host-built binaries in Docker
+
+A binary built by `cargo build` on the host embeds host-absolute source paths (e.g. `/home/user/proj/src/main.rs`) in its DWARF debug info. When the mcp-debugger container mounts the project at `/workspace`, breakpoint requests use `/workspace/...` paths and CodeLLDB cannot match them — file+line breakpoints silently never bind (function breakpoints and pause still work; issue #363).
+
+In container mode (`MCP_CONTAINER=true`) the adapter auto-derives a best-effort `sourceMap` for prebuilt binaries by scanning the binary for embedded host paths whose suffixes exist under the workspace mount (`MCP_WORKSPACE_ROOT`, default `/workspace`). If derivation misses, pass the mapping explicitly — a caller-supplied `sourceMap` always wins:
+
+```json
+{
+  "scriptPath": "/workspace/target/debug/myapp",
+  "dapLaunchArgs": {
+    "sourceMap": { "/home/user/proj": "/workspace" }
+  }
+}
+```
+
+Alternatively, build inside the container (or with `RUSTFLAGS="--remap-path-prefix=/home/user/proj=/workspace"`) so the DWARF paths match the mount directly.
+
 ## Troubleshooting
 
 ### Breakpoints Not Hit
 
@@ -50,6 +50,7 @@ import {
   buildCodeLLDBArgs,
   configurePythonEnvironment,
   resolveTerminalKind,
+  deriveSourceMapFromBinary,
   BinaryInfo
 } from '@debugmcp/codelldb-common';
 import {
@@ -539,6 +540,11 @@ export class CppDebugAdapter extends EventEmitter implements IDebugAdapter {
       postRunCommands: postRunCommands || []
     };
 
+    // Tracks whether the binary was compiled during this launch — a binary
+    // built inside the container already has container paths in its DWARF,
+    // so sourceMap derivation (issue #363) is unnecessary.
+    let compiledAtLaunch = false;
+
     if (program) {
       const programPath = String(program);
 
@@ -558,6 +564,7 @@ export class CppDebugAdapter extends EventEmitter implements IDebugAdapter {
             throw new Error(`C/C++ compile failed: ${result.error}`);
           }
           launchConfig.program = result.binaryPath!;
+          compiledAtLaunch = true;
         } else {
           this.dependencies.logger?.info('[CppDebugAdapter] Using existing binary (up to date)');
           launchConfig.program = outputPath;
@@ -577,6 +584,27 @@ export class CppDebugAdapter extends EventEmitter implements IDebugAdapter {
       await this.evaluateToolchain(launchConfig.program);
     }
 
+    // Container mode (issue #363): a host-built binary embeds host-absolute
+    // DWARF paths, so /workspace breakpoint requests never match. Best-effort:
+    // derive a hostPrefix -> workspaceRoot sourceMap from the binary's
+    // embedded path strings. Caller-supplied sourceMap entries always win.
+    if (
+      process.env.MCP_CONTAINER === 'true' &&
+      !compiledAtLaunch &&
+      Object.keys(sourceMap || {}).length === 0 &&
+      typeof launchConfig.program === 'string' &&
+      launchConfig.program.length > 0
+    ) {
+      const workspaceRoot = process.env.MCP_WORKSPACE_ROOT || '/workspace';
+      const derived = deriveSourceMapFromBinary(launchConfig.program, workspaceRoot);
+      if (Object.keys(derived).length > 0) {
+        launchConfig.sourceMap = derived;
+        this.dependencies.logger?.info(
+          `[CppDebugAdapter] Container mode: derived sourceMap from binary DWARF paths: ${JSON.stringify(derived)}`
+        );
+      }
+    }
+
     return launchConfig;
   }
 
 
@@ -15,7 +15,8 @@ vi.mock('@debugmcp/codelldb-common', async (importOriginal) => ({
   resolveCodeLLDBExecutable: vi.fn(),
   resolveCodeLLDBExecutableSyncImpl: vi.fn(),
   getCodeLLDBVersion: vi.fn(),
-  detectBinaryFormat: vi.fn()
+  detectBinaryFormat: vi.fn(),
+  deriveSourceMapFromBinary: vi.fn()
 }));
 
 vi.mock('../src/utils/compile-utils.js', async (importOriginal) => ({
@@ -30,7 +31,8 @@ import {
   resolveCodeLLDBExecutable,
   resolveCodeLLDBExecutableSyncImpl,
   getCodeLLDBVersion,
-  detectBinaryFormat
+  detectBinaryFormat,
+  deriveSourceMapFromBinary
 } from '@debugmcp/codelldb-common';
 import {
   findCompiler,
@@ -78,6 +80,7 @@ describe('CppDebugAdapter', () => {
     vi.mocked(findAnyCompiler).mockReset();
     vi.mocked(needsRecompile).mockReset();
     vi.mocked(compileSourceFile).mockReset();
+    vi.mocked(deriveSourceMapFromBinary).mockReset().mockReturnValue({});
     dependencies = createDependencies();
     adapter = new CppDebugAdapter(dependencies);
   });
@@ -260,6 +263,100 @@ describe('CppDebugAdapter', () => {
         code: 'SCRIPT_NOT_FOUND'
       });
     });
+
+    describe('container sourceMap derivation (#363)', () => {
+      it('injects a derived sourceMap for a prebuilt binary in container mode', async () => {
+        vi.stubEnv('MCP_CONTAINER', 'true');
+        vi.mocked(deriveSourceMapFromBinary).mockReturnValue({
+          '/home/user/proj': '/workspace'
+        });
+        try {
+          const result = await adapter.transformLaunchConfig({
+            program: 'build/app',
+            cwd: '/work'
+          } as never);
+
+          expect(deriveSourceMapFromBinary).toHaveBeenCalledWith(
+            path.resolve('/work', 'build/app'),
+            '/workspace'
+          );
+          expect(result.sourceMap).toEqual({ '/home/user/proj': '/workspace' });
+        } finally {
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it('respects MCP_WORKSPACE_ROOT for derivation', async () => {
+        vi.stubEnv('MCP_CONTAINER', 'true');
+        vi.stubEnv('MCP_WORKSPACE_ROOT', '/mnt/project');
+        try {
+          await adapter.transformLaunchConfig({ program: 'build/app', cwd: '/work' } as never);
+
+          expect(deriveSourceMapFromBinary).toHaveBeenCalledWith(
+            path.resolve('/work', 'build/app'),
+            '/mnt/project'
+          );
+        } finally {
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it('skips derivation when the caller supplies sourceMap entries', async () => {
+        vi.stubEnv('MCP_CONTAINER', 'true');
+        try {
+          const result = await adapter.transformLaunchConfig({
+            program: 'build/app',
+            cwd: '/work',
+            sourceMap: { '/custom': '/workspace' }
+          } as never);
+
+          expect(deriveSourceMapFromBinary).not.toHaveBeenCalled();
+          expect(result.sourceMap).toEqual({ '/custom': '/workspace' });
+        } finally {
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it('skips derivation outside container mode', async () => {
+        const result = await adapter.transformLaunchConfig({
+          program: 'build/app',
+          cwd: '/work'
+        } as never);
+
+        expect(deriveSourceMapFromBinary).not.toHaveBeenCalled();
+        expect(result.sourceMap).toEqual({});
+      });
+
+      it('skips derivation when the binary was compiled at launch', async () => {
+        vi.stubEnv('MCP_CONTAINER', 'true');
+        const src = path.resolve('/work/hello.cpp');
+        const out = getDefaultOutputPath(src, process.platform);
+        vi.mocked(needsRecompile).mockResolvedValue(true);
+        vi.mocked(compileSourceFile).mockResolvedValue({ success: true, binaryPath: out });
+        try {
+          await adapter.transformLaunchConfig({ program: src } as never);
+
+          expect(deriveSourceMapFromBinary).not.toHaveBeenCalled();
+        } finally {
+          vi.unstubAllEnvs();
+        }
+      });
+
+      it('leaves sourceMap empty when derivation finds nothing', async () => {
+        vi.stubEnv('MCP_CONTAINER', 'true');
+        vi.mocked(deriveSourceMapFromBinary).mockReturnValue({});
+        try {
+          const result = await adapter.transformLaunchConfig({
+            program: 'build/app',
+            cwd: '/work'
+          } as never);
+
+          expect(result.sourceMap).toEqual({});
+        } finally {
+          vi.unstubAllEnvs();
+        }
+      });
+    });
   });
 
   describe('attach support', () => {
 
@@ -412,16 +412,39 @@ class MockDebugAdapterProcess {
     } as DebugProtocol.StoppedEvent);
   }
 
+  /**
+   * Emit a stopped event for a hit breakpoint. Function breakpoints report
+   * reason 'function breakpoint' (issue #355); plain line breakpoints keep
+   * 'breakpoint'. Both carry hitBreakpointIds when the record has an id.
+   */
+  private sendBreakpointStopped(bp: DebugProtocol.Breakpoint & { isFunctionBreakpoint?: boolean }): void {
+    this.sendEvent({
+      seq: 0,
+      type: 'event',
+      event: 'stopped',
+      body: {
+        reason: bp.isFunctionBreakpoint ? 'function breakpoint' : 'breakpoint',
+        threadId: 1,
+        allThreadsStopped: true,
+        ...(bp.id !== undefined ? { hitBreakpointIds: [bp.id] } : {})
+      }
+    } as DebugProtocol.StoppedEvent);
+  }
+
   /**
    * Walk the sorted breakpoint list from a line: logpoint lines emit an
    * output event (naive {expr} interpolation) and do NOT stop; the first
    * plain breakpoint after the line is the next stop (issue #235).
    */
-  private findNextStop(fromLine: number): (DebugProtocol.Breakpoint & { logMessage?: string }) | undefined {
-    const allBreakpoints = Array.from(this.breakpoints.values())
-      .flat()
+  private findNextStop(fromLine: number): (DebugProtocol.Breakpoint & { logMessage?: string; isFunctionBreakpoint?: boolean }) | undefined {
+    const allBreakpoints = (Array.from(this.breakpoints.values())
+      .flat() as (DebugProtocol.Breakpoint & { logMessage?: string; isFunctionBreakpoint?: boolean })[])
       .filter(bp => bp.line !== undefined)
-      .sort((a, b) => (a.line || 0) - (b.line || 0));
+      // Sort by line; when a line breakpoint and a function breakpoint share a
+      // line, the plain line breakpoint wins the tiebreak (issue #355)
+      .sort((a, b) =>
+        ((a.line || 0) - (b.line || 0)) ||
+        ((a.isFunctionBreakpoint ? 1 : 0) - (b.isFunctionBreakpoint ? 1 : 0)));
 
     for (const bp of allBreakpoints) {
       if ((bp.line || 0) <= fromLine) continue;
@@ -480,16 +503,7 @@ class MockDebugAdapterProcess {
         if (firstStop) {
           this.currentLine = firstStop.line || 1;
           this.log(`Hit first breakpoint at line ${this.currentLine}`);
-          this.sendEvent({
-            seq: 0,
-            type: 'event',
-            event: 'stopped',
-            body: {
-              reason: 'breakpoint',
-              threadId: 1,
-              allThreadsStopped: true
-            }
-          } as DebugProtocol.StoppedEvent);
+          this.sendBreakpointStopped(firstStop);
         } else if (this.shouldSimulateException()) {
           this.sendExceptionStopped();
         } else {
@@ -603,8 +617,11 @@ class MockDebugAdapterProcess {
           id: Math.floor(Math.random() * 100000),
           verified: true,
           line,
-          source: { path: this.programPath || 'mock://program' }
-        });
+          source: { path: this.programPath || 'mock://program' },
+          // Marker so the run simulation can report 'function breakpoint'
+          // as the stop reason (issue #355)
+          isFunctionBreakpoint: true
+        } as DebugProtocol.Breakpoint & { isFunctionBreakpoint: boolean });
       } else {
         breakpoints.push({
           id: Math.floor(Math.random() * 100000),
@@ -777,16 +794,7 @@ class MockDebugAdapterProcess {
         // Hit the next breakpoint
         this.currentLine = nextBreakpoint.line;
         this.log(`Stopping at breakpoint on line ${this.currentLine}`);
-        this.sendEvent({
-          seq: 0,
-          type: 'event',
-          event: 'stopped',
-          body: {
-            reason: 'breakpoint',
-            threadId: 1,
-            allThreadsStopped: true
-          }
-        } as DebugProtocol.StoppedEvent);
+        this.sendBreakpointStopped(nextBreakpoint);
       } else if (this.shouldSimulateException()) {
         // Crash before completion: uncaught exception past the last breakpoint
         this.sendExceptionStopped();