release: bump version to 0.53.0

docs/technical/en/ops-planet-sh-startup.md

@@ -22,10 +22,10 @@ image_exists AND stamp_non_empty AND fingerprint_match
 
 ### Fix
 
-The stamp file moved to a persistent cache path:
+The stamp file moved from a temporary location to a persistent cache path:
 
 ```bash
-AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
+AI_PROVIDER_BUILD_STAMP_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/planet/aiprovider_build.sha256"
 ```
 
 Writing the stamp creates the directory first:
@@ -92,7 +92,7 @@ COPY aiprovider /app/aiprovider
 
 ### Runtime Configuration
 
-Before starting AI Provider, `planet.sh` generates a temporary env-file and passes it to Compose or the manual `docker run` fallback. Configuration priority:
+Before starting AI Provider, `planet.sh` generates a current-user runtime env-file and passes it to Compose or the manual `docker run` fallback. The default path is `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`. Configuration priority:
 
 1. `aiprovider/.env`
 2. simple `export AI_...=...` or `AI_...=...` lines from `~/.zshrc`
@@ -188,6 +188,62 @@ Before the stamp path fix:
 
 After moving the stamp file, plain `restart` uses the same `stop + start` behavior and the same fingerprint check as `restart -b`.
 
+## State Files, Logs, and Failed-Start Cleanup
+
+`planet.sh` no longer writes PID files, logs, or runtime env-files to fixed `/tmp/planet_*` paths. The default state directory is:
+
+```bash
+${XDG_STATE_HOME:-$HOME/.local/state}/planet
+```
+
+At startup the script creates this directory and tries to set it to `700`. The current files include:
+
+- `backend.pid` / `frontend.pid` / `motion_agent.pid`
+- `backend.log` / `frontend.log` / `motion_agent.log`
+- `aiprovider_build.log`
+- `aiprovider_runtime.env`
+- `ports.env`
+
+PID writes validate that the PID is a positive integer, include a trailing newline, and try to set file mode `600`. PID reads ignore invalid content instead of passing it to `kill`.
+
+After a successful `start`, the script records the ports in `ports.env`. Later `./planet.sh health` calls prefer the last started ports; if the state file is missing, health checks fall back to the defaults `8000`, `3000`, `8010`, and `8765`. This avoids checking default ports after starting with custom ports.
+
+Startup now has light failed-start cleanup. If `start` exits before completing, the script only cleans local processes that this run already started: backend, frontend, and Motion Agent. It does not stop services after a successful start. AI Provider, PostgreSQL, and Redis keep their existing container lifecycle behavior.
+
+## Health Checks and Hardening
+
+HTTP readiness checks now use `curl -fsS --max-time`, so 4xx and 5xx responses are no longer treated as healthy.
+
+Process termination now validates:
+
+- signal names are limited to `TERM`, `KILL`, `INT`, and `HUP`;
+- PIDs must be positive integers;
+- process group IDs must be positive integers.
+
+This prevents bad PID files or invalid signals from reaching `kill`.
+
+Frontend and Motion Agent startup failures now call `print_port_listener_details()`, matching backend port diagnostics. The Windows-side listener and cleanup path still only runs when WSL is detected.
+
+## Cross-Platform Notes
+
+The script is currently Linux-first with WSL enhancements. Normal Linux runs do not execute the PowerShell path; WSL gets extra Windows listener, portproxy, and camera guidance.
+
+To make this single script fully portable across Linux, macOS, and WSL, the remaining platform differences should be wrapped behind compatibility helpers:
+
+- `stat --format`, `sort -V`, and `xargs -r` are GNU-style and are not fully compatible with default macOS BSD tools.
+- `hostname -I`, `ss`, `fuser`, and `systemctl` are usually unavailable on macOS.
+- `tac` may be missing on macOS; use `awk` or Python as a fallback.
+- Docker Desktop on macOS does not use `systemctl` daemon diagnostics.
+- Camera auto-detection relies on `/dev/video*` / `v4l2-ctl`, which is Linux-specific; macOS should use explicit camera URLs or a separate AVFoundation detector.
+
+The recommended direction is a small platform compatibility layer for port listener detection, version comparison, file metadata, reverse tail, LAN IP discovery, and Docker daemon diagnostics, instead of scattering more platform branches throughout service startup logic.
+
+## Production Delivery Boundary
+
+`planet.sh` is a local development convenience script, not the production startup entrypoint. Production delivery should use Kubernetes `Deployment`, `Service`, `Ingress`, and readiness/liveness probes for ports, health checks, restarts, and rolling upgrades. This removes the need for a host script to reclaim local ports and avoids running the Vite dev server in production.
+
+The production frontend shape is `vite build` static output served by nginx/Caddy or an equivalent HTTP server. Do not use `bun run dev` or `vite preview` in production. The project does not maintain a parallel Webpack build chain; if a future enterprise requirement needs closer Webpack-ecosystem compatibility, run an Rsbuild/Rspack spike first. Electron should only be evaluated when the official target becomes an offline desktop application.
+
 ## Optional Motion Agent Startup
 
 `planet.sh` can now manage the local Motion Capture Agent. It is disabled by default so ordinary development machines do not fail startup when cameras, OpenCV, or MediaPipe are unavailable.