kicks_liveness 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c784de1ca564182e9e36f8fb2956bb61a854c50995bdfe656c68805df671aed
-  data.tar.gz: e40f05ab3385e7b6dd680e040888120693751bda5ff5b2ff2625e107c4ff7cf9
+  metadata.gz: db97cf34081f6a62735363603c3139ff3ddea09c23d81305d2e3a2e2e84ff126
+  data.tar.gz: ca1ee94ae412b24615b4df2eabe3d1344375721f4b50a33ca6af2590c6b60ae3
 SHA512:
-  metadata.gz: e4e1088cc18b3a51493f330e2f37b3eba223dd6b21be77adcaf50833362a29b805d35f7d851ad31a2f84f2d7a9e5b69792cf443fd5cac2e8b2a44e53d70b9f29
-  data.tar.gz: 99345f3a010f4f6c72936e80a81fdff2a6ebf0ea371596bc90850b47cfe5abacaa93694b629fd9121de386e04a5272d44b46b3425f88229ae66c2e3fc0c555f7
+  metadata.gz: 11b5aaed04e4e67c3607a25291d7f1443f5ca00885b0fec3f9931ebc967c02f11deb150697a78f0a936c832334ef895783ec532801d72e61d92e2f2b715a2c67
+  data.tar.gz: dd47406061ce002cd058bd4d89577a383d0eafcc7808688f4d147a660ccd635b6141b75ffa97a6e7778ce661d51cde8b99f0d31e9ce7bf731e4633d84dc9438c

data/CHANGELOG.md

@@ -5,6 +5,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-10-21
+
+### Fixed
+
+- Detect and reject PID topologies in which the container generation cannot
+  identify an incarnation. `shareProcessNamespace: true` and `hostPID: true`
+  leave PID 1 alive across a restart of the worker container, so the 0.1.2
+  identifier can repeat and an inherited fresh heartbeat could satisfy
+  `startupProbe`. Rejection is conditional on a readable `/proc/1/ns/mnt`.
+  Where the comparison can be made, the worker publishes `<dir>/topology-unsafe`
+  instead of a heartbeat and every probe exits 1 with
+  `unsupported PID topology: pod must not set shareProcessNamespace or hostPID`,
+  including one that cannot read the link itself; the state is terminal for the
+  marks volume, and recovery is recreating the pod without those settings.
+  Where it cannot, the previous behavior remains and the worker warns once. The
+  measured outcomes are in `docs/LIMITATIONS.md`.
+- Distinguish a valid zero in PID 1's stat start-time field from a stat line
+  that cannot be parsed: the generation stays unavailable, and the warning
+  names `hostPID` or a virtualized procfs instead of a false parse error.
+- Scope the `attempt-<slot>` respawn counter to the container generation. A
+  replacement container starts its own unhealthy run and cannot escalate over
+  starts it did not take, while respawns within one generation go on sharing a
+  count. Where no generation is available the counter keeps its previous
+  volume-wide behavior.
+
+### Added
+
+- Report a degraded container generation once from the worker, at WARN — once
+  per container incarnation where a generation exists, once per error state
+  where it does not. Neither degraded state adds anything to the probe's
+  output, and the intentional non-Linux fallback stays silent.
+- The marks directory gains two files that appear only when something is
+  wrong: `topology-unsafe`, the terminal fail-closed state, and
+  `topology-report`, the worker's own flag for saying each thing once. Tooling
+  that enumerates the directory should allow for both.
+- Document the boundary of the graceful-shutdown exemption in
+  `docs/LIMITATIONS.md`: a SIGTERM that does not come from a pod deletion can
+  leave a pod Ready with no consumers. Existing behavior, newly documented.
+- Add `spec/integration/verify.sh topology`, a Linux matrix covering a shared
+  PID namespace, the host PID namespace, a verified private-PID container, and
+  a private-PID container whose checker cannot read `/proc/1/ns/mnt`.
+
+### Changed
+
+- `Heartbeat#declare!` documents its actual `Integer` return value.
+- Replace `Heartbeat.container_generation` with `Heartbeat.topology`, returning
+  a structured result instead of a string or `nil`; replace the `Heartbeat.new`
+  keyword `generation:` with `topology:`, accepting that result; and remove
+  `KicksLiveness::GenerationGuard`. All are `@api private`, but callers need
+  updating.
+
+## [0.1.2] - 2026-09-11
+
+### Fixed
+
+- Reject heartbeat files inherited from a previous container incarnation. A
+  Kubernetes `emptyDir` survives container restarts, so a fresh mark left by a
+  formerly healthy worker could make the next container pass `startupProbe`
+  before its consumers had subscribed. Cache files elsewhere in the same
+  `emptyDir` remain untouched and available to warm the next application boot.
+  This protection assumes the default container-private PID namespace; pods
+  using `shareProcessNamespace` or `hostPID` retain the 0.1.1 freshness-only
+  behavior (see `docs/LIMITATIONS.md`).
+  The marks directory now contains `<dir>/generation`, and each
+  `worker-<slot>` mark carries the same value; tooling that enumerates the
+  directory should allow for this new metadata file.
+
 ## [0.1.1] - 2026-09-09
 
 ### Added
@@ -57,6 +124,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   [docs/](https://github.com/PoroshkinaVV/kicks_liveness/tree/main/docs); start
   with `SETUP.md`, and read `LIMITATIONS.md` before relying on it.
 
-[Unreleased]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/PoroshkinaVV/kicks_liveness/releases/tag/v0.1.0

data/README.md

@@ -10,8 +10,19 @@
 Rails or querying RabbitMQ from the probe.**
 
 The worker checks its own Bunny consumers and publishes a heartbeat to tmpfs.
-The probe only reads that heartbeat. No application boot, no network call, and
-no healthy replica hiding a stalled one.
+The probe only reads that heartbeat, scoped to the current container
+incarnation. No application boot, no network call, and no healthy replica
+hiding a stalled one.
+
+That restart scoping needs Kubernetes' default container-private PID
+namespace. Where the namespace links are readable, a pod that sets
+`shareProcessNamespace` or `hostPID` is rejected outright. With the default
+capability set they were not readable on the measured Kubernetes node: the
+shared-PID pod was `unverifiable`, while the host-PID pod had no usable
+generation because node init reported a zero start time. Both degradations warn
+instead of pretending the restart guarantee still holds; see
+[Limitations](docs/LIMITATIONS.md#container-generations-need-linux-procfs-and-a-private-pid-namespace)
+for what each side can prove and what it does when it cannot.
 
 ## Install: one line in Rails
 
@@ -189,7 +200,7 @@ negative path before rollout; the commands and expected output are in
 | [Design](docs/DESIGN.md) | health predicate, heartbeat files, hooks, configuration choices, and measurements |
 | [Running under Kubernetes](docs/KUBERNETES.md) | full manifest, CPU/startup budgets, alerts, and live-pod verification |
 | [Limitations](docs/LIMITATIONS.md) | cases the in-memory predicate intentionally cannot cover |
-| [Verification scenarios](docs/VERIFYING.md) | ten deliberately induced failures and their observed outcomes |
+| [Verification scenarios](docs/VERIFYING.md) | twelve deliberately exercised scenarios and their observed outcomes |
 
 ## Contributing
 

data/docs/DESIGN.md

@@ -40,16 +40,17 @@ outside it can, so let the worker publish and let the probe read.
 
 Every `tick` seconds (10 by default) the worker checks, **in its own memory**,
 that its consumers are still subscribed, and touches a file on tmpfs. The probe
-loads one dependency-free Ruby file, reads the file's mtime, and exits with 0 or
-1.
+loads one dependency-free Ruby file, checks the marks' container generation and
+mtimes, and exits with 0 or 1.
 
 The probe therefore performs no network I/O and boots no framework, and the
-state it reads — the mark's mtime — comes from tmpfs, which is RAM. Be precise
-about the disk, though: starting the probe still loads the Ruby interpreter and
-two files of this gem from the image filesystem, and those reads are ordinary
-filesystem reads (usually served from page cache, but not guaranteed to be). The
-honest claim is not "no disk" but *no application boot, and no disk on the path
-that decides the answer* — which is what removes the defects above, not tuning.
+state it reads — the generation and mark mtimes — comes from procfs and tmpfs.
+Be precise about the disk, though: starting the probe still loads the Ruby
+interpreter and two files of this gem from the image filesystem, and those reads
+are ordinary filesystem reads (usually served from page cache, but not
+guaranteed to be). The honest claim is not "no disk" but *no application boot,
+and no disk on the path that decides the answer* — which is what removes the
+defects above, not tuning.
 
 ## The health predicate
 
@@ -73,9 +74,8 @@ channel.open? && connection.open? && channel.any_consumers?
 | connection open, no consumers | unhealthy | the worker silently stopped consuming — a restart is the only cure |
 | not the whole set subscribed | unhealthy | a worker that quietly dropped out would otherwise leave the probe green |
 
-The last row is the reason the registry compares its size against an expected
-count rather than just checking that whatever registered is alive. Four healthy
-workers out of five look perfectly fine one object at a time.
+The expected count catches partial subscription: four healthy workers out of
+five must still make the process unhealthy.
 
 ### Nothing here talks to the broker
 
@@ -100,64 +100,76 @@ The predicate learns that a consumer was cancelled because RabbitMQ sends
 push, not a poll — which is what makes an in-memory predicate possible at all,
 and also where its limits come from. See [LIMITATIONS.md](LIMITATIONS.md).
 
-`recovering_from_network_failure?` is marked `@private` in Bunny's own
-documentation, so an upgrade may remove it. It is therefore called through
-`respond_to?`: without that guard the call would raise `NoMethodError`, `alive?`
-would catch it and report *unhealthy*, and every pod would enter a restart loop
-on the next Bunny upgrade. What the guard cannot preserve is the exemption
-itself — if the method disappears, so does "healthy while reconnecting",
-silently. That is the thing to re-check when upgrading Bunny.
+`recovering_from_network_failure?` is private Bunny API. The `respond_to?` guard
+avoids turning its removal into a rescued `NoMethodError` and an unhealthy
+verdict on every tick. Removal would still disable the recovery exemption
+silently; re-check this API when upgrading Bunny.
 
 ## The mark files
 
 ```
-<dir>/expected       how many forks the probe must wait for
-<dir>/worker-<slot>  one per fork, refreshed every tick the fork is healthy
-<dir>/attempt-<slot> starts of a slot that has not become healthy yet
+<dir>/expected         how many forks the probe must wait for
+<dir>/generation       which container incarnation wrote this heartbeat
+<dir>/worker-<slot>    one per fork, refreshed every tick the fork is healthy
+<dir>/attempt-<slot>   starts of a slot that has not become healthy yet
+<dir>/topology-unsafe  the PID namespace is not this container's: fail closed
+<dir>/topology-report  what the worker has already reported about it, once
 ```
 
-**`expected` closes a startup hole.** Without it the probe would pass as soon as
-any single file was fresh: fork 0 has written, fork 1 has not, and the pod looks
-ready while half of it is not subscribed. Every fork writes the same value, so
-they cannot disagree.
-
-Every fork rewrites it on every tick, not only at startup. Nothing else restores
-it: if the directory is wiped, `touch!` brings the slot marks back while
-`expected` stays missing, and the probe reports "worker has not started" for the
-rest of the pod's life. Rewriting it is also what lets a respawned set of forks
-correct a count that has been lowered.
-
-**Files are named by supervisor slot, not by PID.** A fork killed with SIGKILL
-is respawned into the same slot and overwrites its own file. Had the name
-contained a PID, that file would sit there stale forever and the probe would
-fail permanently, turning one dead fork into a pod that can never come back.
-
-`expected` is written through a temporary file and a `rename`, not with a plain
-write. A plain write truncates first, and a probe reading in that window finds
-the file empty and reports that the worker has not started. The window is real
-and recurring: every fork rewrites this file on every tick, while the liveness
-probe reads it on a schedule of its own. `rename` is atomic on tmpfs, so the
-probe sees either the old value or the new one.
-
-**`attempt-<slot>` is the respawn counter**, and it lives in this directory for
-the single reason that the directory outlives the fork: a monitor caught in a
-respawn loop is a brand-new object every few hundred milliseconds and can hold
-no counter of its own. The file is removed once the slot becomes healthy, so in
-steady state the directory holds only `expected` and the `worker-<slot>` marks;
-what the counter is for is in
+**`expected` prevents partial startup from passing.** Checking only existing
+marks could accept fork 0's fresh mark before fork 1 has subscribed. Declaring
+the count tells the probe which marks must exist, not just which are fresh.
+With a fixed runner configuration, every fork declares the same count.
+Re-declaring on each tick also restores `expected` if the directory is
+wiped; refreshing slot marks alone would leave the probe permanently unhealthy.
+Live worker-count changes remain
+[unsupported](LIMITATIONS.md#changing-the-worker-count-at-runtime-is-not-supported).
+
+**`generation` rejects inherited heartbeats.** With usable Linux procfs and a
+container-private PID namespace, the worker and exec probe derive it from the
+mount namespace and PID 1 start time. Both `generation` and every slot mark must
+match the current incarnation, so an `emptyDir` preserved across a container
+restart cannot pass `startupProbe` until all replacement forks publish. No
+application cache is removed. Procfs and PID-topology limits are described in
+[LIMITATIONS.md](LIMITATIONS.md#container-generations-need-linux-procfs-and-a-private-pid-namespace).
+
+**`topology-unsafe` carries terminal evidence from the worker.** Each participant
+compares `/proc/1/ns/mnt` with `/proc/self/ns/mnt` independently. A worker that
+proves them different writes this file instead of a heartbeat; the probe checks
+it before `expected`, generation, or freshness. Omitting a new generation would
+leave inherited marks eligible for acceptance. Weaker evidence never clears
+this file.
+
+**`topology-report` deduplicates worker diagnostics across forks.** The probe
+ignores it. Claims lock the complete read-compare-write operation; atomic rename
+alone cannot prevent concurrent claims. Clearing by truncation keeps every fork
+locking the same inode.
+
+**Slot names survive fork replacement.** A respawn overwrites its predecessor's
+mark. PID-based names would leave stale files that permanently fail the probe.
+
+`expected` and slot marks are published through temporary files and `rename`.
+Concurrent probes therefore see complete old or new contents, never a truncated
+count or a mark missing its generation. Temporary filenames include the writer's
+PID so concurrent forks cannot overwrite one another's temporary files.
+
+**`attempt-<slot>` persists an unhealthy run across fork respawns.** Its
+generation rejects counts from a previous container when one can be derived.
+The first healthy tick removes it. Reporting windows and generation-less scope
+are explained in
 [LIMITATIONS.md](LIMITATIONS.md#a-respawn-loop-is-reported-once-per-grace-window-not-once-per-respawn).
 
-The *contents* of `worker-<slot>` (timestamp, pid, slot) exist only for a human
-running `kubectl exec ... cat`. The probe decides on mtime alone.
+The timestamp, pid, and slot in `worker-<slot>` exist for a human running
+`kubectl exec ... cat`. Its generation is part of the probe contract; freshness
+still comes from mtime.
 
-The directory must be on tmpfs — in Kubernetes, an `emptyDir` with
-`medium: Memory`. Put it on a real disk and the probe starts depending on the
-disk again, which was defect number two.
+Use tmpfs — an `emptyDir` with `medium: Memory` in Kubernetes — to keep mark
+reads independent of disk stalls.
 
 ## Why the heartbeat file has no `require` of its own
 
-The probe loads exactly one file and nothing else. Measured over 30 invocations
-each; absolute values depend on the hardware, but the ratios do not:
+The probe entry point loads only `heartbeat.rb`. Recorded over 30 invocations
+each; timings vary with the runtime and hardware:
 
 | | per invocation |
 |---|---|
@@ -167,22 +179,13 @@ each; absolute values depend on the hardware, but the ratios do not:
 | the probe, found through RubyGems | 43 ms |
 | **`bundle exec ruby -e ''`** | **300 ms** |
 
-Subtract the baselines and the probe's own work is a **few milliseconds**.
-Everything else is interpreter startup, and 28 ms of that is RubyGems
-initializing.
-
-Three consequences follow. `bundle exec kicks-liveness` is the portable
-default; most of its runtime is Bundler startup rather than the check itself.
-When the gem is installed in `GEM_HOME`, RubyGems can find it with a plain
-`require` for under 50 ms. Skipping RubyGems entirely is faster still, but it
-requires naming the path to the gem's `lib` directory; see
-[KUBERNETES.md](KUBERNETES.md) for when that trade is worth making.
-
-Keeping the probe's path through the heartbeat file free of `require`
-statements — and the file free of references to the rest of the gem — is what
-makes all three possible. The single `require` the file does contain,
-`fileutils`, is lazy and sits in the directory-creation branch that only the
-worker ever reaches.
+Interpreter and dependency startup dominate these measurements. `bundle exec`
+is the portable default; direct loading depends on where the image installs
+the gem, as described in [KUBERNETES.md](KUBERNETES.md#where-your-image-puts-its-gems).
+`heartbeat.rb` therefore references no other gem code and requires `fileutils`
+only in the worker's directory-creation branch. Worker-only counters and report
+deduplication live in `Attempts` and `TopologyReport` so their code and requires
+stay outside the probe's load path.
 
 ## Where the hooks attach
 
@@ -196,56 +199,36 @@ Railtie in Rails), covering four methods:
 - `Sneakers::WorkerGroup#stop` — record that the shutdown is deliberate, *before*
   `super` starts unsubscribing.
 
-`after_fork` rather than `run`, even though `run` is where the monitor must
-ultimately live: `Sneakers::WorkerGroup#run` calls `after_fork` as its very first
-statement and only then resolves `worker_classes`, so hooking `after_fork` is the
-earliest point in the fork at which the application's own `after_fork` hook has
-already run. That matters because resolving the expected consumer count may run
-application code — under `sneakers:active_job` the set is a callable registry —
-and the standard use of `after_fork` is re-establishing the connections a fork
-inherited. Resolving the set first would run that code against a fork that is not
-ready yet, and the `rescue` around the start would then leave the pod with no
-monitor at all. A spec asserts this ordering against the real worker gem, so an
-upgrade that reorders `run` fails in CI rather than in production.
-
-`ServerEngine::Server#create_worker` calls `w.extend(@worker_module)`: the
-`WorkerGroup` module lands in the singleton class of the *instance*, not as an
-`include` in a class. A `prepend` to the module still sits ahead of it in that
-lookup chain, which is what makes the hook work; `worker_id` and `config` come
-from `ServerEngine::Worker`. Verified on serverengine 2.4.0, and covered by a
-spec that asserts the order in `ancestors` — this is the most fragile assumption
-in the gem, so it fails in CI rather than in production.
+`WorkerGroup#run` calls `after_fork` before resolving `worker_classes`. Starting
+after that hook lets the application restore inherited connections before the
+consumer count runs application code. This matters for the callable registry
+used by `sneakers:active_job`; resolving it too early can prevent monitor startup.
+A spec pins this ordering against the worker gem.
+
+ServerEngine 2.4.0 uses `w.extend(@worker_module)`, placing `WorkerGroup` in the
+instance's singleton-class chain. Prepending to the module still intercepts its
+methods; an `ancestors` spec verifies that assumption. `worker_id` and `config`
+come from `ServerEngine::Worker`.
 
 Slot numbers come from `worker_id`, which is the index into ServerEngine's
 `@monitors` array, and both `start_new_worker(wid)` and `restart_worker(wid)`
 reuse the same index. That is what the slot-not-PID scheme relies on.
 
-The monitor thread is created inside the fork, because threads do not survive
-`fork`. Starting it earlier would accomplish nothing. For the same reason the
-registry initializes its array and mutex at file-load time: that happens once,
-single-threaded, before any fork, so no lazy initialization is needed and none
-can race.
-
-In Rails the hooks are installed from a Railtie, and from `to_prepare` rather
-than an `initializer`. An application's `lib` is normally managed by Zeitwerk and
-reloadable, and reloadable constants must not be referenced while the
-application is initializing.
+The monitor thread is created inside the fork because threads do not survive
+`fork`. The registry's array and mutex are initialized at load time, before
+forking, avoiding races during lazy initialization.
 
-Starting the monitor is wrapped in a `rescue`: instrumentation has no right to
-prevent a worker from starting. `Dir.mkdir` raises `Errno::EROFS` if the marks
-directory was never mounted, and resolving the worker set runs application code.
-The worst outcome should be a missing mark and a pod restart, never a pod that
-stays up with silent queues.
+The Rails Railtie registers installation through `to_prepare`, allowing access
+to reloadable worker constants after initialization. Startup exceptions, from
+either application code or an unwritable marks directory, are logged without
+preventing the worker from starting. The probe remains responsible for detecting
+a missing or stale heartbeat.
 
 ### The expected consumer count is not configured
 
-It is derived from `config[:worker_classes]` — the very set from which the
-worker gem builds its workers. The queue list is therefore never duplicated and
-cannot drift from the application's configuration.
-
-That value is an array of classes under `sneakers:run` and a callable registry
-under `sneakers:active_job`, so it is resolved with a `respond_to?(:call)`
-check.
+`config[:worker_classes]` is the set the worker gem itself consumes: an array
+under `sneakers:run`, a callable registry under `sneakers:active_job`. Resolve it
+with `respond_to?(:call)` rather than maintaining a separate queue list.
 
 ## What is configurable, and where
 
@@ -255,52 +238,28 @@ check.
 | `tick` | either, and the config block wins | only the worker reads it, so two sources cannot contradict each other |
 | `dir`, `max_age` | environment variables **only** | the probe is a separate process |
 
-`dir` and `max_age` are deliberately *not* settable from the application. The
-probe is launched by the kubelet as its own process; it never reads, and cannot
-read, the application's initializer. If those two values were configurable in
-both places, a mismatch between what the worker writes and what the probe
-expects would pass unnoticed — and that mismatch is silent by nature: the worker
-would look fine and the probe would look broken. Making them read-only from the
-application removes the failure mode instead of documenting it. A spec asserts
-that `Configuration` does not respond to `dir=` or `max_age=`.
-
-`tick` is the opposite case and may be set from either side, because only the
-worker ever reads it: with a single reader there is nothing for a mismatch to
-happen between. `KICKS_LIVENESS_TICK` supplies the initial value and the
-configuration block overrides it, so `config.tick = 5` wins over the variable.
-
-Values arriving from a ConfigMap are parsed defensively: garbage falls back to
-the default rather than crashing the worker, and an empty string counts as
-"unset" — in a ConfigMap that is what you get by declaring a key and leaving it
-blank.
-
-`max_age` and `tick` are durations, so a value must be parseable *and* positive.
-Zero and negative numbers are the more dangerous half: they parse perfectly
-well, a tick of zero turns the monitor into a hot loop, and a negative `max_age`
-makes every mark stale on arrival, so the probe can never pass again. They fall
-back to the default too.
-
-Setting `tick` from the application is held to a stricter standard: a
-non-positive value raises `ArgumentError`, as does a value greater than or equal
-to `max_age`: such a monitor would inevitably let a healthy mark go stale. The
-environment gets a silent fallback for values that cannot be parsed. If its
-effective tick is greater than or equal to `max_age`, configuration emits a
-warning on stderr and uses the default tick when it is safe, or half of `max_age`
-otherwise. A ConfigMap typo must not bring a worker down, whereas an initializer
-is code and should fail loudly at boot, where the developer is looking.
-
-`startup_grace_ticks` must be a positive integer. It is compared directly with
-an integer counter; accepting zero, a float, or a string would silently disable
-the escalation that is supposed to diagnose a worker that never subscribes.
-
-The logger defaults to `Sneakers.logger` but is resolved lazily, because at the
-time the configuration object is built it may not be set up yet.
-
-Logging is diagnostic; the heartbeat is the liveness contract. An exception
-raised by a custom logger is therefore swallowed at the logging boundary. It
-cannot prevent a healthy tick from writing its mark, abort monitor startup, or
-escape the loop's error handler and kill the monitor thread. No fallback message
-is attempted through the same broken logger.
+The exec probe cannot read an application initializer, so `dir` and `max_age`
+have one source: the environment. Specs reject application setters for both.
+Only the worker reads `tick`, so `config.tick` may override
+`KICKS_LIVENESS_TICK` without contradicting the probe.
+
+Environment durations must be positive integers; missing, empty, unparseable,
+zero, and negative values use defaults. If the effective tick is at least
+`max_age`, it warns on stderr and uses the default tick when safe, or half of
+`max_age` otherwise. The warning is deferred until the tick is read, so an
+initializer override or a disabled monitor does not produce a misleading WARN.
+
+Invalid ConfigMap input falls back so a deployment typo does not prevent worker
+startup. Initializer values are application code: invalid values raise
+`ArgumentError` at boot, where the developer can fix the error, rather than
+silently substituting a default. `tick` must be a positive number smaller than
+`max_age`, and `startup_grace_ticks` a positive integer. The latter is compared
+with an integer counter; accepting a float or zero would disable escalation.
+
+The default logger is resolved lazily from `Sneakers.logger`, which may be unset
+during configuration. Logger exceptions are swallowed at the logging boundary
+so they cannot prevent heartbeat publication or stop the monitor. No fallback
+uses the same broken logger.
 
 ## Logging: events, not the pulse
 
@@ -310,30 +269,29 @@ add noise. What gets logged is transitions.
 | Event | Level |
 |---|---|
 | started, with the effective settings | INFO |
+| the PID topology could not be verified, or yielded no generation | WARN |
 | waiting for consumers | INFO |
 | became healthy | INFO |
 | shutting down | INFO |
 | still not healthy after `startup_grace_ticks` ticks | ERROR |
 | was healthy, became unhealthy | ERROR |
 | a slot respawning without ever becoming healthy, once per grace window | ERROR |
+| the PID topology is proven unsupported | ERROR |
 | the monitor thread caught an exception | ERROR |
 | the monitor could not be started at all | ERROR |
 
-ERROR is reserved for genuine failure. A logger typically comes up with
-`LOG_LEVEL` defaulting to `error`, so anything important must survive that
-filter — while an ordinary pod start must not emit ERROR on every deploy, or an
-alert on ERROR logs fires on every rollout and is promptly muted.
-
-A graceful shutdown is the other half of that rule. `Sneakers::Worker#stop`
-unsubscribes and then waits for the thread pool to drain, which takes as long as
-the longest in-flight job — and the registry empties at the start of it. Judged
-by the consumer count that is indistinguishable from a fault, so every single
-deploy would emit an ERROR. From `WorkerGroup#stop` onwards the predicate is
-therefore suspended: the monitor says so once at INFO and keeps the mark fresh,
-so a slow drain gets the full `terminationGracePeriodSeconds` instead of having
-the probe cut it short at `max_age`.
-
-The startup grace exists because a slow start and a start that will never finish
-look identical for the first few ticks. Once the grace expires, staying silent
-would mean a pod that never comes up never says so — hence exactly one ERROR,
-not one per tick.
+`topology-report` deduplicates only the three topology results: `unverifiable`,
+`unavailable`, and `unsafe`. Their warning frequency, probe output, and recovery
+are described in
+[LIMITATIONS.md](LIMITATIONS.md#container-generations-need-linux-procfs-and-a-private-pid-namespace).
+Loop and startup exceptions do not use that flag.
+
+ERROR must survive the usual error-level logger filter, while normal startup
+and deliberate shutdown remain INFO. On shutdown the monitor suspends its
+predicate and refreshes the mark for the rest of the process, assuming an
+[external deadline](LIMITATIONS.md#graceful-shutdown-is-safe-only-when-something-else-owns-the-deadline).
+
+Startup grace postpones the error for a slow initial subscription; a surviving
+monitor reports once when it expires. Fork-respawn loops use the persistent
+counter and reporting windows described in
+[LIMITATIONS.md](LIMITATIONS.md#a-respawn-loop-is-reported-once-per-grace-window-not-once-per-respawn).

data/docs/KUBERNETES.md

@@ -46,6 +46,26 @@ Without `medium: Memory` an `emptyDir` is backed by the node's disk, and the
 probe starts depending on the disk again — which is one of the things it exists
 to avoid.
 
+An `emptyDir` deliberately survives a restart of the container inside its pod.
+That keeps a Bootsnap or other application cache under `/opt/app/tmp` warm for
+the next attempt, but it also leaves the previous process's heartbeat files in
+`health/`. The gem does not clear the volume or that directory. Instead it
+records the current Linux container generation separately and in every slot
+mark. A fresh mark from the previous container is rejected until every fork in
+the current one has subscribed and published its own mark, so preserving the
+cache cannot make `startupProbe` succeed early.
+
+That guarantee needs the default container-private PID namespace. Do not set
+`shareProcessNamespace: true` or `hostPID: true`: in either topology PID 1
+survives a worker-container restart, so the generation repeats and an inherited
+mark would be accepted. Since 0.1.3 the gem rejects that topology when either
+the worker or probe can read and compare both namespace links. With Kubernetes'
+default capability set those reads failed on the measured node: the shared-PID
+pod was `unverifiable`, and the host-PID pod was `unavailable` because node init
+reported a zero start time. Those states warn and retain the documented degraded
+checks; they do not claim the topology is safe. See
+[LIMITATIONS.md](LIMITATIONS.md#container-generations-need-linux-procfs-and-a-private-pid-namespace).
+
 ## Why the command looks like that
 
 **`bundle exec kicks-liveness` is the standard command.** It works regardless
@@ -104,6 +124,15 @@ executable is found regardless of `BUNDLE_PATH`, which is why it is the standard
 command. Run bare, it depends on the gem's `bin` directory being on `PATH`,
 which is not something to rely on in a manifest.
 
+Keep the worker and probe on the same gem version. Since 0.1.2 the heartbeat
+protocol includes a container generation; a newer probe correctly rejects the
+generation-less files written by an older worker. Since 0.1.3 it also includes
+the fail-closed topology state, which only a 0.1.3 probe reads: an older probe
+beside a 0.1.3 worker would ignore a proven unsupported PID topology instead of
+failing on it. `bundle exec` guarantees that both sides resolve from the same
+bundle. If the faster form below installs a second copy in `GEM_HOME`, rebuild
+that copy on every gem upgrade too.
+
 ### Where your image puts its gems
 
 Before replacing the standard command with plain Ruby, run this against your