core: close the container-handle UX gaps (audit group B)

The public umbrella now really covers the API it promises: Network.hpp
and Volume.hpp were unreachable from testcontainers.hpp (GenericImage
only forward-declares Network), so umbrella-only users could not compile
Network::create() / Volume::builder(). Compile-checked by tc_smoke.

Container::stop() gains the grace-period parameter stop_container
already had (unset = create-time StopTimeout, 0 = kill now, negative =
wait indefinitely); new Container::start() restarts a stopped handle
through the OWNED client (a custom-daemon container restarts against
its own daemon) - a plain daemon start: waits/hooks do not re-run, the
once-fired stopping hooks stay fired, ephemeral ports re-bind (live
get_host_port() re-resolves; cached module getters keep their values,
as their docs already state). Integration test
Lifecycle.StopStartRoundTrip covers stop(0), restart, exec-after-
restart, and the already-running 304 path.

Pipeline: MSVC 559 units, full Linux core integration 135 pass/44 skip,
WSL gcc 553 units, clang-tidy and clang-format clean. Opus review:
SHIP; both nits applied (PID-1 SIGTERM comment wording).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0141x8KrNdD9NfmCh1vSMbpg

Author: cppudge

docs/feature-notes.md

@@ -135,7 +135,14 @@ composition over `GenericImage`.
 `with_startup_attempts(n)` (the whole create→start→wait retried, each failed partial removed;
 the reuse-adopt path is not retried; no inter-attempt backoff). A throwing created/starting/
 started hook aborts start() and cleans up; stopping fires once on teardown — never for a
-persistent (reuse) handle — and its exceptions are swallowed.
+persistent (reuse) handle — and its exceptions are swallowed. `Container::stop(timeout_secs)`
+(2026-07-12) forwards the daemon grace period (unset = the container's create-time
+StopTimeout, default 10s; 0 = kill now; negative = wait indefinitely), and
+`Container::start()` restarts a stopped handle through the OWNED client (so a
+custom-daemon container restarts against its own daemon) — a plain daemon start: waits and
+hooks do not re-run, the once-fired stopping hooks stay fired, and ephemeral published
+ports are re-bound (re-resolve via `get_host_port()`; a module's Started* getters keep
+their start()-time values).
 
 **Reaper (Ryuk)** — containers, networks, named volumes, and built images carry the session
 label; compose stacks are covered by an extra per-project filter registered over the same

docs/public-api-test-coverage.md

@@ -160,7 +160,8 @@ on Windows only the inline-Dockerfile + build-error round-trip is exercised.
 | `read_file(path)` | ✅ | ✅ [b] | ✅ Copy.ReadFileRoundTrip, Copy.LargeFileRoundTrip, Copy.ReadFileRejectsDirectory | ✅ WindowsCopy.ReadFileRoundTrip, WindowsCopy.LargeFileRoundTrip, WindowsCopy.ReadFileRejectsDirectory |
 | `copy_file_from(path, host)` | ✅ | ✅ [b] | ✅ Copy.CopyFileFromWritesHost | ✅ WindowsCopy.CopyFileFromWritesHost |
 | `resize_tty(size)` | ✅ | ✅ | ✅ Tty.ResizeTtyChangesWindowSize | ❌ (ConPTY resize untested; Linux path covers the client-side wire) |
-| `stop()` | ✅ | ✅ | ✅ Lifecycle.StoppingHookFiresOnStop | ❌ |
+| `stop(timeout_secs)` | ✅ | ✅ | ✅ Lifecycle.StoppingHookFiresOnStop, Lifecycle.StopStartRoundTrip (explicit zero grace) | ❌ |
+| `start()` (restart a stopped handle) | ✅ | ✅ | ✅ Lifecycle.StopStartRoundTrip (incl. the already-running 304 path) | ❌ |
 | `is_running()` | ✅ | ✅ | ✅ RedisMvp, WaitStrategies.* | ✅ WindowsContainer.ExecRunsInRunningContainer |
 | `keep(bool)` | ✅ | ✅ | ✅ Lifecycle.KeepLeavesContainerRunning (+ unit Runner.KeepSkipsRemovalOnDrop, Runner.KeepFalseRearmsRemovalOnDrop) | ❌ (client-side flag; engine-independent) |
 | `inspect(id)` (static) | ✅ | ✅ | ✅ Lifecycle.StaticInspectById (found + NotFoundError) | ❌ (same code path as `inspect_container`) |

include/testcontainers/Container.hpp

@@ -3,6 +3,7 @@
 #include <chrono>
 #include <cstdint>
 #include <filesystem>
+#include <optional>
 #include <string>
 #include <utility>
 #include <vector>
@@ -211,8 +212,21 @@ class Container {
 
     /// Stop the container (an auto-removing handle still removes it on
     /// destruction; a persistent handle — `with_reuse` / after `keep()` —
-    /// does not).
-    void stop();
+    /// does not). `timeout_secs` is the grace period before the daemon kills
+    /// the process: unset uses the container's create-time StopTimeout
+    /// (default 10s), 0 kills immediately, negative waits indefinitely.
+    /// Stopping hooks fire once, before the stop.
+    void stop(std::optional<int> timeout_secs = std::nullopt);
+
+    /// Start the container again after a `stop()` (`POST
+    /// /containers/{id}/start`; already-running is accepted). A plain
+    /// daemon-side start: the request's wait strategies and lifecycle hooks
+    /// do NOT re-run, and the stopping hooks — fired once by the earlier
+    /// `stop()` — stay fired. The daemon re-binds ephemeral published ports
+    /// on start: re-resolve them through `get_host_port()` (a module's
+    /// Started* getters keep their original values). Throws DockerError on
+    /// failure.
+    void start();
 
     /// Whether the container is currently running (per a fresh inspect).
     bool is_running() const;

include/testcontainers/testcontainers.hpp

@@ -10,7 +10,9 @@
 #include "testcontainers/Error.hpp"
 #include "testcontainers/GenericBuildableImage.hpp"
 #include "testcontainers/GenericImage.hpp"
+#include "testcontainers/Network.hpp"
 #include "testcontainers/Ulimit.hpp"
+#include "testcontainers/Volume.hpp"
 #include "testcontainers/WaitFor.hpp"
 #include "testcontainers/docker/DockerClient.hpp"
 #include "testcontainers/docker/DockerHost.hpp"

src/Container.cpp

@@ -161,11 +161,17 @@ void Container::copy_file_from(const std::string& container_path,
     }
 }
 
-void Container::stop() {
+void Container::stop(std::optional<int> timeout_secs) {
     // Explicit stop is a teardown point: fire the stopping hooks (once) before
     // the container is stopped.
     fire_stopping();
-    client_.stop_container(id_);
+    client_.stop_container(id_, timeout_secs);
+}
+
+void Container::start() {
+    // Through the OWNED client on purpose: a container run against a custom
+    // daemon (run(client, request)) restarts against that same daemon.
+    client_.start_container(id_);
 }
 
 bool Container::is_running() const { return client_.inspect_container(id_).running; }

tests/integration/LifecycleTest.cpp

@@ -7,6 +7,7 @@
 
 #include "testcontainers/Container.hpp"
 #include "testcontainers/Error.hpp"
+#include "testcontainers/ExecResult.hpp"
 #include "testcontainers/GenericImage.hpp"
 #include "testcontainers/Lifecycle.hpp"
 #include "testcontainers/WaitFor.hpp"
@@ -20,6 +21,7 @@
 //   Lifecycle.HooksFireInOrder - created/starting/started hooks fire once, in that order, each seeing the live container id.
 //   Lifecycle.StoppingHookFiresOnStop - a stopping hook fires when the container is explicitly stopped.
 //   Lifecycle.StartupRetriesOnFailure - with_startup_attempts(2) retries the whole create→start→wait on failure, creating a fresh container each attempt.
+//   Lifecycle.StopStartRoundTrip - stop(0) (explicit zero grace) stops the container, start() brings the same container back (a plain daemon start; exec works again), and a second start() is accepted as already-running.
 //   Lifecycle.KeepLeavesContainerRunning - keep() releases removal ownership: after the handle drops, the container is still running (verified and cleaned up via an adopted RemoveOnDrop handle).
 //   Lifecycle.StaticInspectById - the static Container::inspect(id) reads a running container's state without a handle and throws NotFoundError for an id that does not exist.
 //   WindowsLifecycle.HooksFireInOrder - the same hook ordering against a Windows daemon (the hooks are client-side, but each leg drives real Windows-engine create/start calls).
@@ -104,6 +106,27 @@ TEST_F(Lifecycle, StartupRetriesOnFailure) {
     EXPECT_EQ(created_count, 2);
 }
 
+TEST_F(Lifecycle, StopStartRoundTrip) {
+    Container c = GenericImage::from_reference(kImage).with_cmd({"sleep", "60"}).start();
+
+    // Explicit zero grace: the container's sleep (PID 1, no SIGTERM handler)
+    // would burn the full grace period before the daemon's SIGKILL — zero
+    // grace just skips that wait.
+    c.stop(0);
+    EXPECT_FALSE(c.is_running());
+
+    // A plain daemon start on the SAME container: no waits or hooks re-run.
+    c.start();
+    EXPECT_TRUE(c.is_running());
+    // exec proves the restarted container is live, not merely flagged running.
+    const ExecResult res = c.exec({"echo", "back"});
+    EXPECT_EQ(res.exit_code, 0);
+    EXPECT_EQ(res.stdout_data, "back\n");
+
+    c.start(); // already running: the daemon's 304 is accepted, not an error
+    EXPECT_TRUE(c.is_running());
+}
+
 TEST_F(Lifecycle, KeepLeavesContainerRunning) {
     // keep() releases removal ownership: the handle's drop leaves the container
     // running, exactly like a with_reuse handle would.