v12.3.8

datalab-to/suryav12.3.8Apr 21, 2026by thedotmack

AI Summary

Fix for PID reuse detection in worker start-guard to allow containers to restart cleanly, using process-start identity tokens instead of just liveness checks.

Key Highlights

  • Detect PID reuse via process-start identity token
  • Linux: /proc/<pid>/stat field 22 (starttime in jiffies)
  • macOS/POSIX: ps -p <pid> -o lstart= with LC_ALL=C
  • Backwards compatibility for token-less PID files
  • DEBUG log for PID reuse cases

New Features

  • Process-start identity token capture
  • verifyPidFileOwnership with token verification
  • Backwards compatibility for older PID files
  • Container restart scenario fix

Full Release Notes

## 🔧 Fix

**Detect PID reuse in the worker start-guard so containers can restart cleanly.** (#2082)

The `kill(pid, 0)` liveness check false-positived when the worker's PID file outlived its PID namespace — most commonly after `docker stop` / `docker start` with a bind-mounted `~/.claude-mem`. The new worker would boot as the same low PID (often 11) as the old one, `kill(0)` would report "alive," and the worker would refuse to start *against its own prior incarnation*. Symptom: container appeared to start, immediately exited cleanly with no user-visible error, worker never came up.

### What changed

- Capture an opaque **process-start identity token** alongside the PID and verify identity, not just liveness:
  - **Linux**: `/proc/<pid>/stat` field 22 (starttime in jiffies) — cheap, no exec, same signal `pgrep`/`systemd` use.
  - **macOS / POSIX**: `ps -p <pid> -o lstart=` with `LC_ALL=C` pinned so the emitted timestamp is locale-independent across environments.
  - **Windows**: unchanged — falls back to liveness-only. The PID-reuse scenario doesn't affect Windows deployments the way containers do.
- `verifyPidFileOwnership` emits a DEBUG log when liveness passes but the token mismatches, so the "PID reused" case is distinguishable from "process dead" in production logs.
- PID files written by older versions are token-less; `verifyPidFileOwnership` falls back to the existing liveness-only behavior for backwards compatibility. **No migration required.**

### Surface

Shared helpers (`PidInfo`, `captureProcessStartToken`, `verifyPidFileOwnership`) live in `src/supervisor/process-registry.ts` and are re-exported from `ProcessManager.ts` to preserve the existing public surface. Both entry points updated: `worker-service.ts` GUARD 1 and `supervisor/index.ts` `validateWorkerPidFile`.

### Tests

+14 new tests covering token capture, ownership verification, backwards compatibility for tokenless PID files, and the container-restart regression scenario. Zero regressions.