Implement automatic namespace lifecycle cleanup with last-man-out reference counting

1 files changed, 5 insertions, 2 deletions

diff --git a/README.md b/README.md
index 90b243c..650c3e6 100644
--- a/README.md
+++ b/README.md
@@ -130,8 +130,11 @@ Routing traffic to the VPN doesn't guarantee DNS is routed.
     - **User Control**: Provide a flag (e.g., `--dns-server <IP>`) to allow the user to override the fallback and specify their own trusted resolver.
 
 ### 3. Namespace Lifecycle
-Network namespaces can leak if not managed.
-- **Action**: The controller must monitor the target process and explicitly tear down the TUN device and close the namespace on exit.
+Network namespaces can leak if not managed. To prevent this, `wg-wrap` implements a "last-man-out" reference counting system:
+- **Tracking**: Every process using a profile creates a PID file in `/run/user/$UID/wg-wrap/profiles/<name>/pids/`.
+- **Automatic Cleanup**: When a process exits, it removes its PID file. If no PID files remain for a profile, `wg-wrap` automatically unpins the namespace and terminates the associated userspace WireGuard process.
+- **Resilience**: Stale PID files (from crashed processes) are pruned during the initial join sequence of any new process.
+- **Manual Override**: The controller also provides `wg-wrap profile stop <name>` to force the immediate teardown of a profile's namespace.
 
 ### 4. User Namespace Sequence
 To create a network namespace without root, you must create a user namespace first.