feat: IPC lifecycle redesign — per-PID sockets, flock guard, daemon.addr discovery

Replace fragile PID lockfile + fixed socket/pipe names with:
- Per-PID unique addresses (daemon-{pid}.sock / \.\pipe\punkgo-kernel-{pid})
- flock on daemon.addr for single-instance guard (OS auto-releases on crash)
- daemon.addr file for service discovery (pid + endpoint)
- --replace flag for graceful daemon replacement via IPC shutdown command

Eliminates stale socket "Address already in use" (macOS) and
"Access Denied" (Windows) errors after unclean daemon shutdown.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: FeilixX

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to PunkGo Kernel will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-13
+
+### Changed
+
+- **IPC lifecycle redesign** — daemon now uses per-PID socket/pipe names (`daemon-{pid}.sock` / `\\.\pipe\punkgo-kernel-{pid}`), eliminating stale socket/pipe issues after crashes on all platforms
+- **Single-instance guard** — replaced PID lockfile with `flock` on `daemon.addr` (auto-released on process death by OS)
+- **Service discovery** — daemon writes `daemon.addr` file with PID + endpoint; clients read it to find the daemon
+- **`--replace` flag** — gracefully stops old daemon via IPC shutdown command, then takes over
+- **IPC shutdown command** — `kind: "shutdown"` request triggers graceful daemon shutdown
+
+### Removed
+
+- PID lockfile (`daemon.pid`) — superseded by flock on `daemon.addr`
+- Interactive "Kill it? [y/N]" prompt — replaced by `--replace` flag
+
 ## [0.3.0] - 2026-03-13
 
 ### Fixed

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 authors = ["Felix <feijiu@punkgo.ai>"]
 license = "MIT"
@@ -32,3 +32,4 @@ toml = "0.8"
 tempfile = "3.16"
 uuid = { version = "1.21.0", features = ["v4", "serde"] }
 interprocess = { version = "2.4", features = ["tokio"] }
+fs2 = "0.4"

Cargo.toml

@@ -17,7 +17,7 @@ default = []
 testkit = []
 
 [dependencies]
-punkgo-core = { path = "../punkgo-core", version = "0.3.0" }
+punkgo-core = { path = "../punkgo-core", version = "0.4.0" }
 anyhow.workspace = true
 async-trait.workspace = true
 serde.workspace = true
@@ -31,6 +31,7 @@ tracing.workspace = true
 tracing-subscriber.workspace = true
 uuid.workspace = true
 interprocess.workspace = true
+fs2.workspace = true
 
 [dev-dependencies]
 tempfile.workspace = true

crates/punkgo-kernel/Cargo.toml

@@ -4,8 +4,9 @@ use interprocess::local_socket::{
     GenericFilePath, GenericNamespaced, ListenerOptions, Name, ToFsName, ToNsName,
     traits::tokio::Listener as _,
 };
-use punkgo_core::protocol::{RequestEnvelope, ResponseEnvelope};
+use punkgo_core::protocol::{RequestEnvelope, RequestType, ResponseEnvelope};
 use punkgo_kernel::Kernel;
+use serde_json::json;
 use tokio::io::{AsyncBufReadExt, AsyncRead, AsyncWrite, AsyncWriteExt, BufReader};
 use tracing::{error, info, warn};
 
@@ -17,23 +18,32 @@ fn endpoint_to_name(endpoint: &str) -> std::io::Result<Name<'_>> {
     }
 }
 
-pub async fn run_ipc_server(kernel: Arc<Kernel>, endpoint: &str) -> std::io::Result<()> {
+pub async fn run_ipc_server(
+    kernel: Arc<Kernel>,
+    endpoint: &str,
+    shutdown_tx: tokio::sync::watch::Sender<bool>,
+) -> std::io::Result<()> {
     let name = endpoint_to_name(endpoint)?;
     let listener = ListenerOptions::new().name(name).create_tokio()?;
     info!(endpoint = endpoint, "IPC server listening");
 
     loop {
         let conn = listener.accept().await?;
         let kernel = Arc::clone(&kernel);
+        let shutdown_tx = shutdown_tx.clone();
         tokio::spawn(async move {
-            if let Err(err) = handle_connection(conn, kernel).await {
+            if let Err(err) = handle_connection(conn, kernel, shutdown_tx).await {
                 warn!(error = %err, "IPC client disconnected with error");
             }
         });
     }
 }
 
-async fn handle_connection<S>(stream: S, kernel: Arc<Kernel>) -> std::io::Result<()>
+async fn handle_connection<S>(
+    stream: S,
+    kernel: Arc<Kernel>,
+    shutdown_tx: tokio::sync::watch::Sender<bool>,
+) -> std::io::Result<()>
 where
     S: AsyncRead + AsyncWrite + Unpin,
 {
@@ -58,6 +68,25 @@ where
         };
         info!(request_id = %request.request_id, "ipc request received");
 
+        // Check for shutdown command before dispatching to kernel.
+        if matches!(request.request_type, RequestType::Read) {
+            if let Some(kind) = request
+                .payload
+                .get("kind")
+                .and_then(serde_json::Value::as_str)
+            {
+                if kind == "shutdown" {
+                    let response = ResponseEnvelope::ok(
+                        request.request_id.clone(),
+                        json!({"message": "shutting down"}),
+                    );
+                    write_response(&mut writer, &response).await?;
+                    let _ = shutdown_tx.send(true);
+                    return Ok(());
+                }
+            }
+        }
+
         let response = kernel.handle_request(request).await;
         if let Err(err) = write_response(&mut writer, &response).await {
             error!(error = %err, "failed to write IPC response");