kicks_liveness 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df61d00933097bb96e6d752e024e349ab631cd7c9d571cd9bff9ff63b8adda40
-  data.tar.gz: 78864373ca06cd998cdee192d064cd00ed69a4ecd73eb1b657474d77ab593066
+  metadata.gz: faf817806eb5142b8271959b7856a16db10a99db8eed583bb5594887198b6dd8
+  data.tar.gz: 9c5f3f845c78a56e5da97204769e5c2b10161fbf56e5c40a731b904650ca469a
 SHA512:
-  metadata.gz: '007091e18fea1b216ba25c634bab1a4770d25cc0f062ee30ba2885563075bc94e7662e58eebbac9507b448217508725612f172189b692e3a4d616e5f81fdd46b'
-  data.tar.gz: f460271ca68fdf912559b3fa2c41b02074d5eb457e946d2f985e3e2b0ac3da66dc94ce90c9d5639212a0fc7bb6537046654f31921cf6766fe15c903bd7dc04ef
+  metadata.gz: a077fc085bed4c460ed9820940271fedb44e69a2778ca87997b23c172fe94d0622bbf334d9b5456827d1e231813ec5e903de6ebe6c655804f8b8c359ca26832c
+  data.tar.gz: 1d2efdab9aa59777cc14075703c9c75bfad76dc511d94659a8f2f40d2cc8a3a957779e4795f304beabbed04c4854f88e2413fd044216497df7338d6a7a32a864

data/CHANGELOG.md

@@ -5,6 +5,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-11-03
+
+### Fixed
+
+- Bound the graceful-shutdown heartbeat exemption by a monotonic deadline
+  starting at the first stop notification; repeated callbacks cannot extend it.
+  At expiry the monitor logs one ERROR and stops refreshing its mark, but still
+  declares the fork count. A stuck drain then fails the ordinary freshness
+  check; the monitor does not kill the process.
+
+### Added
+
+- Add `shutdown_grace` / `KICKS_LIVENESS_SHUTDOWN_GRACE` (default 60 seconds;
+  initializer wins). Set it to at least `terminationGracePeriodSeconds`.
+  Restart still waits for mark staleness and the kubelet's probe failure budget.
+- Add `verify.sh shutdown` and `container-restart` to check a real drain and
+  same-pod container replacement, with deployment restoration afterwards.
+- Add an `install!` setup hint when the probe finds no declared worker count.
+  It remains a failing check, not proof that the hooks were never installed.
+
+## [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
@@ -73,7 +144,9 @@ 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.2...HEAD
+[Unreleased]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.3...v0.1.4
+[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

@@ -14,10 +14,15 @@ 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 assumes Kubernetes' default container-private PID
-namespace; see
-[Limitations](docs/LIMITATIONS.md#container-generations-require-linux-procfs-and-container-owned-pid-1)
-for pods that set `shareProcessNamespace` or `hostPID`.
+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
 
@@ -72,6 +77,9 @@ only when every expected worker mark is present and fresh.
 Use a startup probe for the boot budget and a liveness probe for steady state:
 
 ```yaml
+        env:
+          - name: KICKS_LIVENESS_SHUTDOWN_GRACE
+            value: "60"           # at least terminationGracePeriodSeconds
         startupProbe:
           exec:
             command: ["bundle", "exec", "kicks-liveness"]
@@ -134,6 +142,7 @@ environment too:
 | `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | heartbeat directory; must be on tmpfs | uses the default |
 | `KICKS_LIVENESS_MAX_AGE` | `45` | seconds before a mark is stale | uses the default |
 | `KICKS_LIVENESS_TICK` | `10` | seconds between worker checks | uses the default, then the safety fallback below if needed |
+| `KICKS_LIVENESS_SHUTDOWN_GRACE` | `60` | seconds to keep publishing during shutdown | uses the default |
 
 If the effective environment tick is not smaller than `max_age`, the worker
 writes a WARN to stderr and uses `10` seconds when that is safe, or half of
@@ -141,10 +150,16 @@ writes a WARN to stderr and uses `10` seconds when that is safe, or half of
 while guaranteeing that a healthy heartbeat cannot become stale between
 ordinary ticks.
 
-An initializer value for `tick` wins over `KICKS_LIVENESS_TICK`. `dir` and
+Initializer values for `tick` and `shutdown_grace` override their environment
+variables. `dir` and
 `max_age` deliberately have no initializer setters: allowing two configuration
 sources could make the worker and probe silently disagree.
 
+Set `shutdown_grace` to at least `terminationGracePeriodSeconds`. A drain that
+exceeds this deadline stops refreshing its heartbeat and logs one ERROR; the
+probe fails once the last mark becomes stale. See
+[shutdown timing](docs/LIMITATIONS.md#graceful-shutdown-has-a-finite-heartbeat-exemption).
+
 If two runners share one pod — for example `sneakers:run` and
 `sneakers:active_job` — give each a different `KICKS_LIVENESS_DIR`. Separate
 pods already have separate `emptyDir` volumes.
@@ -195,7 +210,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) | eleven 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

@@ -74,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
 
@@ -101,84 +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>/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>/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.
-
-**`generation` closes a container-restart hole when the container owns PID 1.**
-Kubernetes preserves an `emptyDir` when it restarts a container inside the same
-pod. That is useful for an application cache elsewhere in the volume, but a
-fresh heartbeat from the dead process must not let the new container pass its
-one-shot `startupProbe`. On Linux, the worker and exec probe independently
-derive the same incarnation from the container's mount namespace and PID 1
-start time. Both `generation` and every slot mark carry it. Until the new
-container declares itself and every current fork publishes its own mark, files
-inherited from the previous container are rejected. Nothing outside the marks
-directory is removed.
-
-This guarantee assumes Kubernetes' default container-private PID namespace.
-With `shareProcessNamespace: true` PID 1 belongs to the pod sandbox, and with
-`hostPID: true` it is the node init process; neither restarts with the worker
-container. Under either setting the guard can accept an inherited fresh mark.
-Do not enable them on a pod whose startup probe relies on this guarantee; see
-[LIMITATIONS.md](LIMITATIONS.md#container-generations-require-linux-procfs-and-container-owned-pid-1).
-
-**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 `expected`, `generation`, 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 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 |
 |---|---|
@@ -188,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
 
@@ -217,111 +199,71 @@ 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.
+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.
 
-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.
-
-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
 
 | Setting | Where | Why |
 |---|---|---|
 | `logger`, `enabled`, `startup_grace_ticks` | application config block | only the worker needs them |
-| `tick` | either, and the config block wins | only the worker reads it, so two sources cannot contradict each other |
+| `tick`, `shutdown_grace` | either, and the config block wins | only the worker reads them, 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` and `shutdown_grace`, so initializer values may
+override their environment values 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.
+
+`KICKS_LIVENESS_SHUTDOWN_GRACE` defaults to 60 seconds. Its initializer override
+accepts positive finite real numbers. Set it to at least the deployment's
+`terminationGracePeriodSeconds`, which the gem cannot discover from a signal.
+
+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
 
@@ -331,30 +273,33 @@ 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 until a monotonic deadline: the first `Registry.stopping!` records the
+stop time, and the monitor adds `shutdown_grace`. A delayed tick or repeated
+callback cannot renew it. At expiry it logs one ERROR and stops `touch!` while
+continuing `declare!`. Nothing is persisted, so a replacement fork does not
+inherit a sibling's shutdown. Mark freshness still uses wall time; see the
+[timing boundary](LIMITATIONS.md#graceful-shutdown-has-a-finite-heartbeat-exemption).
+
+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).