kicks_liveness 0.1.2 → 0.1.4

data/docs/VERIFYING.md

@@ -35,12 +35,32 @@ spec/integration/verify.sh up      # namespace, broker, worker
 spec/integration/verify.sh down    # deletes the namespace
 ```
 
+The Docker form of scenario 11 and scenario 12 need no cluster or broker.
+
 Every `kubectl` call names its context and namespace explicitly, so the script
 never falls back to `current-context`. It will still operate on whichever target
 you configure: run `status` and inspect both values before `up` or `down`. The
 script labels namespaces it creates and refuses to apply to or delete an
 existing namespace without that ownership label.
 
+For another local cluster, export `KICKS_LIVENESS_K8S_CONTEXT` and
+`KICKS_LIVENESS_DOCKER_CONTEXT` before building. `KICKS_LIVENESS_K8S_NAMESPACE`
+selects the disposable namespace; `KICKS_LIVENESS_IMAGE` and
+`KICKS_LIVENESS_RABBITMQ_IMAGE` select local worker and broker images.
+Run the direct recipes below from the repository root with this guarded helper:
+
+```bash
+export KICKS_LIVENESS_K8S_CONTEXT="${KICKS_LIVENESS_K8S_CONTEXT:-docker-desktop}"
+export KICKS_LIVENESS_K8S_NAMESPACE="${KICKS_LIVENESS_K8S_NAMESPACE:-kicks-liveness}"
+k() {
+  local owner
+  owner="$(kubectl --context "$KICKS_LIVENESS_K8S_CONTEXT" get namespace \
+    "$KICKS_LIVENESS_K8S_NAMESPACE" -o 'jsonpath={.metadata.labels.app\.kubernetes\.io/managed-by}')" || return
+  [ "$owner" = kicks-liveness-fixture ] || { echo 'not a fixture namespace' >&2; return 1; }
+  kubectl --context "$KICKS_LIVENESS_K8S_CONTEXT" --namespace "$KICKS_LIVENESS_K8S_NAMESPACE" "$@"
+}
+```
+
 The default image uses Kicks. Build it with Sneakers instead without editing the
 fixture:
 
@@ -101,11 +121,11 @@ expected  generation  worker-0            # in the marks directory
 1 process(es) healthy                     # probe, exit 0
 ```
 
-The hooks fired inside a real ServerEngine fork, which no double can show. On a
-fresh fixture the first attempt also prints `started:`. Do not use that line as
-the sole proof after a same-pod container restart: an inherited unhealthy-run
-counter deliberately suppresses repeated start lines, as described in
-[LIMITATIONS.md](LIMITATIONS.md#a-respawn-loop-is-reported-once-per-grace-window-not-once-per-respawn).
+The hooks fired inside a real ServerEngine fork, which no double can show. The
+`started:` line is also valid proof after a same-pod container restart: since
+0.1.3 the respawn counter carries the container generation, so a replacement
+container reports its own first start rather than continuing the previous
+container's unhealthy run.
 
 ### 2. A stale mark
 
@@ -113,6 +133,14 @@ The recipe from KUBERNETES.md. Proves the probe's threshold and the
 self-repair, and nothing else — the mark is fixed on the next tick, well inside
 `failureThreshold`, so the container is never killed.
 
+```bash
+pod="$(k get pods -l app=worker -o jsonpath='{.items[0].metadata.name}')"
+k exec "$pod" -- touch -d '120 seconds ago' /opt/app/tmp/health/worker-0
+spec/integration/verify.sh probe  # both commands print stale and exit=1
+sleep 12
+spec/integration/verify.sh probe  # both commands print healthy and exit=0
+```
+
 Worth running through **both** commands here, since this is the one scenario
 where the probe is supposed to answer `1`. `spec/integration/verify.sh probe`
 does exactly that: the standard `bundle exec kicks-liveness` and the optimised
@@ -128,7 +156,9 @@ worker-0 stale 120s > 45s   # exit 1
 The one that matters. Delete a queue the worker consumes from:
 
 ```bash
-kubectl exec deploy/rabbitmq -- rabbitmqctl delete_queue kicks_liveness.alpha
+k exec deploy/rabbitmq -- rabbitmqctl delete_queue kicks_liveness.alpha
+k get pods -l app=worker -w  # watch RESTARTS increase; Ctrl-C after recovery
+spec/integration/verify.sh probe  # exit=0 after the worker re-declares the queue
 ```
 
 Observed, from the moment of deletion:
@@ -162,7 +192,10 @@ not in the pod log. An exec probe's stdout goes nowhere else, which is why
 ### 4. The broker dies
 
 ```bash
-kubectl delete pod -l app=rabbitmq --grace-period=0 --force
+k delete pod -l app=rabbitmq --grace-period=0 --force
+k rollout status deploy/rabbitmq --timeout=300s  # the Deployment recreates it
+spec/integration/verify.sh logs 100
+spec/integration/verify.sh probe
 ```
 
 The pod must **not** restart. "It survived" is not enough on its own — a broker
@@ -182,7 +215,16 @@ consumers back on its own.
 
 ### 5. The broker stays dead
 
-`kubectl scale deploy/rabbitmq --replicas=0`, then wait. Observed over 319 s
+```bash
+k scale deploy/rabbitmq --replicas=0
+sleep 150  # longer than max_age + periodSeconds * failureThreshold
+spec/integration/verify.sh probe  # still exit=0 during Bunny recovery
+k get pods -l app=worker  # RESTARTS must not increase
+k scale deploy/rabbitmq --replicas=1  # restore, including after an interrupted check
+k rollout status deploy/rabbitmq --timeout=300s
+```
+
+With the broker scaled to zero, observed over 319 s
 — seven times `max_age`, more than twice the 135 s steady-state budget — the
 mark's age never exceeded 9 s and `restartCount` stayed 0. The monitor kept
 writing, because `recovering_from_network_failure?` never stops being true:
@@ -207,10 +249,82 @@ quickly — the monitor never gets to run again, so
 `shutting down: consumers are no longer checked` may not appear at all. The
 absence of ERROR is the observable, not the presence of that line.
 
+The shutdown exemption is now bounded by `shutdown_grace` (60 seconds by
+default). Keep `KICKS_LIVENESS_SHUTDOWN_GRACE` at least as long as the fixture's
+`terminationGracePeriodSeconds`. An out-of-band SIGTERM does not start a kubelet
+termination deadline: if the process remains stuck draining, the expected
+monitor diagnostic after its grace is:
+
+```
+[liveness] slot 0: shutdown grace expired: heartbeat is no longer refreshed
+```
+
+The probe can still pass until the last mark exceeds `max_age`; afterwards it
+must exit 1 with `worker-0 stale ...`, and the monitor must not refresh that
+mark on later ticks. The deadline, repeated callbacks, wall-clock changes, and
+a sibling fork's independent lifetime are covered without Kubernetes by:
+
+```bash
+bundle exec rspec spec/kicks_liveness/configuration_spec.rb \
+  spec/kicks_liveness/monitor_spec.rb spec/probe_spec.rb
+```
+
+The probe spec launches a separate Ruby process against the monitor's marks.
+For the real worker and broker, run:
+
+```bash
+spec/integration/verify.sh shutdown
+```
+
+This temporarily uses `tick=1`, `max_age=3`, `shutdown_grace=10` and pod
+termination grace 10 seconds, then restores the original deployment even on
+failure. First it holds a job, rolls out a worker, releases the job only after
+the old pod's first shutdown tick, and requires the job to finish and no
+liveness ERROR; how long the replacement takes to become Ready does not matter.
+Then it blocks a real pool drain, sends SIGTERM without deleting the pod,
+removes the remaining idle consumer, and checks zero consumers, an initially
+healthy probe, one expiry ERROR, an unchanged mark, a stale probe, and a kubelet
+restart restoring both consumers. It releases the blocking job during recovery.
+
+Recorded on 2026-10-21 with 0.1.4: both paths passed on OrbStack Kubernetes
+v1.30.7+orb1, Linux arm64 6.12.10-orbstack-00297-gf8f6e015b993, Docker 27.4.1,
+Ruby 3.4.11, Kicks 3.4.0, Bunny 3.4.0 and the openssl gem 4.0.2, using an image
+built with `--no-cache --pull`. The stuck pod's `restartCount` changed from 0
+to 1.
+
+Replayed on 2026-10-21–22 on the same cluster with Sneakers 2.11.0 /
+ServerEngine 2.0.7 and Sneakers 2.12.0 / ServerEngine 2.1.1, both on Ruby
+3.4.11 and Bunny 2.24.0: both drain paths passed, including the kubelet restart
+and restored consumers. These images used cached layers and local gem packages,
+not another clean online build.
+
+Separate manual pod-deletion checks held the job beyond `shutdown_grace=3s`,
+with `tick=1s`, `max_age=3s` and Kubernetes termination grace 20 seconds. On
+both Sneakers versions and Kicks 3.4.0, an expired mark stayed unchanged and
+both probe commands failed, but the terminating container was not restarted.
+Releasing the job after expiry let it finish with exit 0 in 10.4–11.6 seconds
+from deletion; leaving it blocked caused kubelet to kill it with exit 137 in
+20.8–20.9 seconds. Each run logged expiry once and recovered a healthy
+replacement. The expiry ERROR is expected with this deliberately shorter
+exemption; normal deployments should keep it at least as long as pod grace.
+
 ### 7. Bad broker credentials
 
 Point `AMQP_URL` at a wrong password. The fork cannot subscribe, so the
-supervisor respawns it every `start_worker_delay`, forever. Over 120 s:
+supervisor respawns it every `start_worker_delay`, forever. The new pod never
+passes its startup probe, so the rollout keeps the old healthy pod running and
+`deploy/worker` may resolve to either one; read the newest pod by name. Over
+120 s:
+
+```bash
+amqp="$(k get deploy worker -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="AMQP_URL")].value}')"
+k set env deploy/worker AMQP_URL=amqp://guest:wrong@rabbitmq:5672
+sleep 120
+new="$(k get pods -l app=worker --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1:].metadata.name}')"
+k logs "$new" --tail=30000 | grep liveness
+k set env deploy/worker "AMQP_URL=$amqp"  # restore even if the check fails
+k rollout status deploy/worker --timeout=300s
+```
 
 | | lines |
 |---|---|
@@ -243,6 +357,18 @@ find them.
 `WORKER_COUNT=2` needs no rebuild; the rake task turns it into
 `config[:workers]`.
 
+```bash
+k set env deploy/worker WORKER_COUNT=2
+k rollout status deploy/worker --timeout=300s
+spec/integration/verify.sh probe  # 2 process(es) healthy
+pod="$(k get pods -l app=worker -o jsonpath='{.items[0].metadata.name}')"
+k exec "$pod" -- touch -d '120 seconds ago' /opt/app/tmp/health/worker-1
+spec/integration/verify.sh probe  # worker-1 alone makes it fail
+sleep 12  # the monitor repairs the mark
+k set env deploy/worker WORKER_COUNT=1
+k rollout status deploy/worker --timeout=300s
+```
+
 ```
 INFO: [liveness] slot 0: started: ... processes=2 consumers=2
 INFO: [liveness] slot 1: started: ... processes=2 consumers=2
@@ -264,6 +390,17 @@ because KUBERNETES.md claims the startup probe *incidentally fixes rollouts
 where the old pod was removed before the new one had subscribed* — and that
 claim is about ordering, which needs two pods to be watched at once.
 
+```bash
+k set env deploy/worker WORKER_COUNT=2
+k rollout status deploy/worker --timeout=300s
+# In a second shell with the same exports and helper, watch until rollout completes:
+# while true; do k exec deploy/rabbitmq -- rabbitmqctl -q list_queues name consumers; sleep 1; done
+k rollout restart deploy/worker
+k rollout status deploy/worker --timeout=300s
+k set env deploy/worker WORKER_COUNT=1  # restore; stop the watcher with Ctrl-C
+k rollout status deploy/worker --timeout=300s
+```
+
 `kubectl rollout restart deploy/worker`, with `WORKER_COUNT=2`, so a fully
 subscribed pod is worth two consumers per queue. Counting consumers on the
 broker is what makes the ordering visible:
@@ -294,14 +431,14 @@ treatment as everything else here. The broker in this fixture is enough to check
 it; the plugin is not on by default:
 
 ```bash
-kubectl exec deploy/rabbitmq -- rabbitmq-plugins enable rabbitmq_prometheus
+k exec deploy/rabbitmq -- rabbitmq-plugins enable rabbitmq_prometheus
 ```
 
 Then read all three endpoints from the worker pod, which has a Ruby but no
 `curl`:
 
 ```bash
-kubectl exec deploy/worker -- ruby -rnet/http -e \
+k exec deploy/worker -- ruby -rnet/http -e \
   'puts Net::HTTP.get(URI("http://rabbitmq:15692/metrics/detailed?family=queue_consumer_count"))'
 ```
 
@@ -320,6 +457,15 @@ metric is a *different* name from the aggregate, the detailed endpoint needs the
 Then check the two halves of the alert against a throwaway queue — declare one
 with no consumers, scrape, delete it, scrape again:
 
+```bash
+k exec deploy/worker -- bundle exec ruby -rbunny -e \
+  'c = Bunny.new(ENV.fetch("AMQP_URL")).start; c.create_channel.queue("kicks_liveness.tmpcheck"); c.close'
+# Repeat the scrape above: tmpcheck must have a zero-consumer series.
+k exec deploy/rabbitmq -- rabbitmqctl delete_queue kicks_liveness.tmpcheck
+# Repeat the scrape: tmpcheck must have no series, not a zero.
+k exec deploy/rabbitmq -- rabbitmq-plugins disable rabbitmq_prometheus  # restore
+```
+
 ```
 -- queue exists, zero consumers
    rabbitmq_detailed_queue_consumers{vhost="/",queue="kicks_liveness.tmpcheck"} 0
@@ -362,10 +508,120 @@ The namespace inode is allowed to be reused, as in the example above; the PID 1
 start time still distinguishes the two incarnations. The test removes its
 container and named volume on exit.
 
+The command also prints the topology it ran under, which for an ordinary
+container is the fully verified one:
+
+```
+generation-restart: topology=verified
+```
+
 This scenario covers the default container-private PID namespace. With
 `shareProcessNamespace: true` or `hostPID: true`, PID 1 survives the worker
-container restart and this guarantee does not hold; see
-[LIMITATIONS.md](LIMITATIONS.md#container-generations-require-linux-procfs-and-container-owned-pid-1).
+container restart and this guarantee cannot hold — scenario 12 is that case,
+showing both fail-closed rejection when the topology can be proved and the
+degraded outcomes when procfs access cannot prove it.
+
+The Kubernetes counterpart also leaves `attempt-0` in the pod's `emptyDir`:
+
+```bash
+spec/integration/verify.sh container-restart
+```
+
+It makes PID 1 exit itself through a fixture-only WINCH handler, not an ignored
+in-namespace SIGKILL or ServerEngine's USR2 reload. It requires the same pod,
+an increased `restartCount`, exit 137, a surviving volume witness, a changed
+generation, one replacement `started:` line without inherited escalation, and
+a healthy probe; the original deployment is restored afterwards. On the
+environment recorded in scenario 6, all checks passed with `restartCount=0->1`.
+The same check also passed for both Sneakers versions recorded there.
+The Docker form was also rerun: PID 1 start time changed from 1515589 to 1515784
+with mount namespace inode 4026534862 unchanged; inherited marks were rejected
+until the delayed replacement writer published.
+
+### 12. Shared and host PID topology outcomes
+
+The four PID topologies, in one command. It needs the fixture image but neither
+Kubernetes nor RabbitMQ, because everything here turns on which PID namespace
+the worker container is in:
+
+```bash
+spec/integration/verify.sh build
+spec/integration/verify.sh topology
+```
+
+Recorded on Linux 6.12 (arm64), Docker 27.4.1, ruby 3.4.10:
+
+```
+shared-pid: topology=unsafe
+shared-pid: 0.1.2 generation before=mnt:[4026532693]:17207878 after=mnt:[4026532693]:17207878
+shared-pid inherited heartbeat: exit=1 unsupported PID topology: pod must not set shareProcessNamespace or hostPID
+shared-pid: marks directory holds expected generation topology-unsafe worker-0
+shared-pid after the worker published: exit=1 unsupported PID topology: pod must not set shareProcessNamespace or hostPID
+host-pid: topology=unsafe
+host-pid: 0.1.2 generation before=mnt:[4026532699]:105 after=mnt:[4026532699]:105
+host-pid inherited heartbeat: exit=1 unsupported PID topology: pod must not set shareProcessNamespace or hostPID
+host-pid: marks directory holds expected generation topology-unsafe worker-0
+host-pid after the worker published: exit=1 unsupported PID topology: pod must not set shareProcessNamespace or hostPID
+private-pid: topology=verified
+private-pid: exit=0 1 process(es) healthy
+unverifiable: topology=unverifiable
+unverifiable: warnings across three fork respawns=1
+unverifiable inherited heartbeat: exit=1 heartbeat belongs to a previous container: worker has not started yet
+unverifiable own heartbeat: exit=0 1 process(es) healthy
+```
+
+Four cases, and each line is the point of one of them.
+
+A separate run on a real Kubernetes v1.25.0 node on Docker Desktop used
+containerd, no `securityContext`, a root worker and the default capability set.
+It produced a different and operationally important table:
+
+| pod topology | PID 1 | PID 1 UID | `/proc/1/ns/mnt` | start time | 0.1.3 state |
+|---|---|---:|---|---:|---|
+| `hostPID: true` | node init | 0 | denied | 0 | `unavailable` |
+| `shareProcessNamespace: true` | pod sandbox | 65535 | denied | 19031096 | `unverifiable` |
+| private PID | container process | 0 | readable | 19031243 | `verified` |
+| shared PID plus `CAP_SYS_PTRACE` | pod sandbox | 65535 | readable | — | `unsafe` |
+
+The Docker matrix proves the fail-closed branch by granting the access it needs;
+the Kubernetes measurement shows that this is not the default result for either
+unsupported setting. The degraded states still warn, but they retain the weaker
+generation or freshness-only guarantees described in LIMITATIONS.md.
+
+**`shared-pid`** joins another container's PID namespace, which is what
+Kubernetes `shareProcessNamespace: true` does — there PID 1 is the pod sandbox.
+**`host-pid`** uses the node's PID namespace, which is `hostPID: true`. In both,
+the run publishes a complete, fresh heartbeat in the **0.1.2 format**, restarts
+only the worker container, and recomputes the 0.1.2 identifier by the 0.1.2
+rule. The `before`/`after` pair is the defect being reproduced rather than
+argued about: both halves repeat, including the mount namespace inode, which the
+kernel handed straight back to the replacement container. A 0.1.2 probe would
+have accepted those inherited marks. The revised probe rejects the topology
+before it ever looks at them, and the worker then adds `topology-unsafe` beside
+the inherited files rather than a heartbeat of its own.
+
+Reading PID 1's namespace link is a ptrace-level operation, so the `host-pid`
+case runs with `CAP_SYS_PTRACE`; without it the link is unreadable and the
+outcome depends on whether a generation can still be derived. Node init on the
+measured Kubernetes node reported start time zero, so that pod was
+`unavailable`. A readable positive start time would instead leave the topology
+`unverifiable`. The fourth case below constructs that latter branch explicitly;
+both are honest limits on what a container can prove about a topology it is not
+allowed to inspect.
+
+**`private-pid`** is the fully verified positive control: an ordinary container,
+owning PID 1, probe green.
+
+**`unverifiable`** is the second positive control, and the one that has to stay
+green: a private-PID container whose checker cannot read `/proc/1/ns/mnt`. The
+0.1.2 generation check is kept in full — a heartbeat from another generation is
+still rejected, its own is still accepted — and the cost is exactly one worker
+warning across three fork respawns, not a probe that is permanently red.
+
+That case is constructed by running the checker as a user other than PID 1's.
+It is **not** a model of a Kubernetes exec probe, which has no user setting of
+its own and normally inherits the container process credentials; it is simply
+the one way to make a namespace link unreadable without a custom procfs mount.
 
 ## What to do with a disagreement
 

data/lib/kicks_liveness/attempts.rb

@@ -3,23 +3,18 @@ require 'fileutils'
 module KicksLiveness
   # Counts starts of a supervisor slot that have not reached healthy yet.
   #
-  # Deliberately separate from {Heartbeat}. Heartbeat is the contract shared
-  # with the probe and is loaded by it alone, so nothing the probe does not need
-  # belongs there — including the +fileutils+ this class requires freely.
+  # Persistent state survives fork respawns; its generation separates container
+  # incarnations when available. Kept outside {Heartbeat} because the probe does
+  # not read these counters.
   #
-  # The count lives in the marks directory rather than in memory because a
-  # respawn storm destroys process state every few hundred milliseconds: the
-  # supervisor brings a failing fork back after +start_worker_delay+, and every
-  # incarnation of the monitor believes it is the first. That is how an outage
-  # can produce thousands of identical INFO lines and not one ERROR. The
-  # directory is the only state that survives the fork.
-  #
-  # @see file:docs/DESIGN.md#logging-events-not-the-pulse
+  # @see file:docs/LIMITATIONS.md#a-respawn-loop-is-reported-once-per-grace-window-not-once-per-respawn
   # @api private
   class Attempts
     # @param dir [String] marks directory
-    def initialize(dir)
+    # @param generation [String, nil] container incarnation the count belongs to
+    def initialize(dir, generation: nil)
       @dir = dir
+      @generation = generation
     end
 
     # Records a start of this slot.
@@ -62,22 +57,32 @@ module KicksLiveness
       File.join(@dir, "attempt-#{slot}")
     end
 
-    # A missing or unreadable counter means "no previous start", never an
-    # exception: this is instrumentation, and it may not break a worker.
+    # Missing, unreadable, or foreign-generation counts start a new run.
+    # Counter failures must not prevent worker startup.
     def read(slot)
-      count, epoch = File.read(path(slot)).split
+      count, epoch, generation = File.read(path(slot)).split
+      return [0, nil] unless same_generation?(generation)
+
       [Integer(count), Time.at(Integer(epoch)).utc]
     rescue StandardError
       [0, nil]
     end
 
+    def same_generation?(declared)
+      return true unless @generation
+
+      declared == "generation=#{@generation}"
+    end
+
     # Failing to write degrades the reporting back to one line per respawn,
     # which is noisy but harmless — so a read-only directory is swallowed here
     # rather than escalated.
     def write(slot, count, first)
       FileUtils.mkdir_p(@dir)
+      contents = "#{count} #{first.to_i}"
+      contents = "#{contents} generation=#{@generation}" if @generation
       tmp = "#{path(slot)}.#{Process.pid}"
-      File.write(tmp, "#{count} #{first.to_i}\n")
+      File.write(tmp, "#{contents}\n")
       File.rename(tmp, path(slot))
     rescue StandardError
       nil

data/lib/kicks_liveness/configuration.rb

@@ -3,11 +3,8 @@ require_relative 'heartbeat'
 module KicksLiveness
   # What the application may configure, and what comes from the environment only.
   #
-  # +dir+ and +max_age+ are deliberately read-only here: the probe runs as a
-  # separate process launched by the container runtime and cannot read the
-  # application's initializer. Were they settable in both places, a mismatch
-  # between what the worker writes and what the probe expects would pass
-  # unnoticed.
+  # dir and max_age are environment-only: the separate exec probe cannot read
+  # an application initializer and must resolve the same values as the worker.
   #
   # @see file:docs/SETUP.md#configuration
   # @see file:docs/DESIGN.md#what-is-configurable-and-where
@@ -16,6 +13,8 @@ module KicksLiveness
     DEFAULT_TICK = 10
     # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
     DEFAULT_STARTUP_GRACE_TICKS = 6
+    # @return [Integer] seconds to keep publishing while the workers drain
+    DEFAULT_SHUTDOWN_GRACE = 60
 
     # Seconds between checks. An incompatibility warning for an environment
     # fallback is delayed until this value is actually used, so an initializer
@@ -27,6 +26,8 @@ module KicksLiveness
     end
     # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
     attr_reader :startup_grace_ticks
+    # @return [Numeric] seconds allowed for graceful shutdown, measured monotonically
+    attr_reader :shutdown_grace
     # @return [Logger, nil] explicit logger; defaults to +Sneakers.logger+
     attr_accessor :logger
     # @param value [Boolean] set false to start no monitor thread, e.g. in tests
@@ -37,6 +38,7 @@ module KicksLiveness
       @enabled = true
       @logger = nil
       @tick = environment_tick
+      @shutdown_grace = Heartbeat.env_int(:shutdown_grace, DEFAULT_SHUTDOWN_GRACE)
     end
 
     # @return [Boolean]
@@ -44,10 +46,8 @@ module KicksLiveness
       @enabled
     end
 
-    # A tick is what the monitor thread sleeps on, so a non-positive value is
-    # not a setting but a broken monitor. An initializer is code, and code
-    # should fail loudly at boot, where the developer is looking. Environment
-    # input is resolved separately by {#environment_tick}, with a safe fallback.
+    # Initializer values fail at boot; environment input uses a safe fallback
+    # through {#environment_tick}.
     #
     # @param seconds [Numeric]
     # @raise [ArgumentError] if not a positive number
@@ -75,6 +75,21 @@ module KicksLiveness
       @startup_grace_ticks = ticks
     end
 
+    # Only the monitor reads this value, so an initializer may override the
+    # environment. Keep it at least as long as terminationGracePeriodSeconds.
+    # An infinite value would restore the unbounded shutdown exemption.
+    #
+    # @param seconds [Numeric] finite, positive duration
+    # @raise [ArgumentError] unless +seconds+ is a positive finite real number
+    # @return [Numeric]
+    def shutdown_grace=(seconds)
+      unless seconds.is_a?(Numeric) && seconds.real? && seconds.finite? && seconds.positive?
+        raise ArgumentError, "shutdown_grace must be a positive finite number, got #{seconds.inspect}"
+      end
+
+      @shutdown_grace = seconds
+    end
+
     # Read-only, sourced from the environment so that it matches what the probe
     # sees.
     # @return [String] marks directory