Merge branch 'main' into claude/issue-1196-20251222-1314

Author: hcourdent

docs/advanced/security_isolation/index.mdx

@@ -116,9 +116,11 @@ UNSHARE_ISOLATION_FLAGS="--user --map-root-user --pid --fork --mount-proc"
 What each flag does:
 
 - `--user --map-root-user` - Creates user namespace and maps current user to root inside it
-- `--pid --fork` - Creates isolated PID namespace
+- `--pid --fork` - Creates isolated PID namespace (both flags required together)
 - `--mount-proc` - Mounts isolated /proc filesystem (requires privileged mode in Docker)
 
+**Note**: The `--fork` flag is required when using `--pid`. Custom configurations must include `--fork` for PID namespace isolation to work correctly.
+
 #### Custom flags
 
 You can customize the isolation flags:
@@ -137,6 +139,22 @@ UNSHARE_ISOLATION_FLAGS="--pid --fork --mount-proc"
 
 **Recommendation**: Use the default flags with `privileged: true` for best security. Only use truly unprivileged mode if you cannot enable privileged mode and understand the security tradeoffs.
 
+#### Tini for signal handling
+
+When PID namespace isolation is enabled and tini is available, Windmill uses [tini](https://github.com/krallin/tini) as PID 1 inside the namespace. Tini properly handles signal forwarding, which ensures:
+
+- OOM-killed processes return exit code 137 (128 + SIGKILL) instead of ambiguous errors
+- Zombie processes are properly reaped
+- Signals are correctly forwarded to child processes
+
+Tini is included in the official Windmill Docker images. If tini is not available, Windmill falls back to running without it (with a warning about potentially incorrect OOM exit codes).
+
+You can customize the tini path:
+
+```bash
+UNSHARE_TINI_PATH=/custom/path/to/tini
+```
+
 ### Failure behavior
 
 If `ENABLE_UNSHARE_PID=true` but unshare is unavailable or fails, **the worker will panic at startup** with a detailed error message:

docs/core_concepts/47_environment_variables/index.mdx

@@ -27,6 +27,7 @@ You can use them in a Script by clicking on "+Context Var":
 | ENABLE_UNSHARE_PID        | false (true in docker-compose) | Enable PID namespace isolation to protect process memory and environment variables. Linux only. See [Security and Process Isolation](/docs/advanced/security_isolation)                   | Worker                |
 | DISABLE_NSJAIL            | true                   | NSJAIL sandboxing status. Default `true` means NSJAIL is **disabled**. Set to `false` to enable NSJAIL (requires `-nsjail` image). See [Security and Process Isolation](/docs/advanced/security_isolation) | Worker                |
 | UNSHARE_ISOLATION_FLAGS   | --user --map-root-user --pid --fork --mount-proc | Customize unshare isolation flags when ENABLE_UNSHARE_PID is true. See [Security and Process Isolation](/docs/advanced/security_isolation)                                    | Worker                |
+| UNSHARE_TINI_PATH         | tini                   | Path to tini binary for PID 1 signal handling in unshare namespaces. Ensures correct OOM exit codes. See [Security and Process Isolation](/docs/advanced/security_isolation)  | Worker                |
 | LICENSE_KEY (EE only)     | None                   | License key checked at startup for the Enterprise Edition of Windmill                                                                                                                              | Worker                |
 | SLACK_SIGNING_SECRET      | None                   | The signing secret of your Slack app. See [Slack documentation](https://api.slack.com/authentication/verifying-requests-from-slack)                                                                | Server                |
 | COOKIE_DOMAIN             | None                   | The domain of the cookie. If not set, the cookie will be set by the browser based on the full origin                                                                                               | Server                |