Starstruk Logo MarkStarstruk

v12.3.8

thedotmack/claude-memv12.3.8Apr 21, 2026by thedotmack

AI Summary

Bug fix addressing PID reuse false-positives in the worker start-guard that caused containers to appear to start but immediately exit cleanly when using docker stop/start with bind-mounted ~/.claude-mem. The fix introduces process-start identity tokens to verify process identity beyond just liveness.

Key Highlights

  • Fixed PID reuse detection using process-start identity tokens instead of just kill(pid, 0) liveness checks
  • Linux implementation uses /proc/<pid>/stat field 22 (starttime in jiffies) - same method as pgrep/systemd
  • macOS/POSIX uses ps -o lstart with LC_ALL=C for locale-independent timestamps
  • Windows unchanged - falls back to liveness-only since PID-reuse scenario doesn't affect Windows containers
  • Backwards compatible with older tokenless PID files - no migration required

New Features

  • Process-start identity token capture and verification system
  • DEBUG logging to distinguish 'PID reused' from 'process dead' scenarios
  • 14 new tests covering token capture, ownership verification, and container-restart regression

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.