hooks/README.md

@@ -38,10 +38,8 @@ The hook is synchronous: the host waits. That is the point, because the
 checkpoint has to exist before the change does.
 
 Budget for the slow path, not the fast one. A successful tag took about 4s
-against a healthy VPG, but a **refusal took 63s**: `wait_for_tag` waits 45s for
-a checkpoint that is never going to appear, which is exactly what happens on a
-VPG whose protected site is AWS or Azure, where tagged checkpoints are not
-supported.
+against a healthy vSphere-protected VPG, but a **refusal took 63s**, because
+`wait_for_tag` spends 45s before giving up.
 
 So:
 
@@ -59,9 +57,8 @@ Against a live ZVM 10.9.10, all six rows of the table above. Two worth naming:
 
 - `jp-ubuntu` (healthy, local VPG) tagged checkpoint 7180 and allowed the call,
   passing the tag back through `additionalContext`.
-- `win2019-1` (VPG `CMH-AWS-1`, protected site AWS) was **denied**: Zerto cannot
-  insert a tagged checkpoint there, so the change would not have been
-  recoverable.
+- `win2019-1` (VPG `CMH-AWS-1`, protected site AWS) was **denied**. The deny path
+  works, but see the known issue below: that particular denial was wrong.
 
 Both decisions held with `permission_mode: bypassPermissions`. A hook still
 blocks when the user has turned permissions off, which is when an agent is most
@@ -70,3 +67,27 @@ likely to be running unattended.
 ## Log
 
 `~/.zerto-guard-hook.log`, or `ZERTO_HOOK_LOG`. One line per decision.
+
+## Known issue: false denials on cloud-protected VPGs
+
+The `win2019-1` denial above was a **false negative**, and it is worth
+understanding before relying on this hook in an estate with cloud-protected
+workloads.
+
+`wait_for_tag` gives up after a hardcoded 45s. That is generous for a
+vSphere-protected VPG, which checkpoints every 5s and surfaces a tag in about
+4s. It is far too short elsewhere: a tag takes ~34s to appear on an
+Azure-protected VPG and ~128s on an AWS-protected one, because journal cadence
+is set by the protected site (5s vSphere, 60s Azure, 630s AWS).
+
+So the hook denied the change, and the checkpoint landed anyway. It is in the
+journal as `cp 56`, timestamped a minute after the hook reported failure. The
+guard told the agent there was no rewind point while Zerto was in the middle of
+creating one.
+
+That failure mode is worse than the one the hook guards against, because it is
+silent and looks correct: legitimate work is refused on every cloud-protected VM
+while the log reads like the guard is doing its job.
+
+Until `wait_for_tag` becomes cadence-aware, scope this hook's matcher to
+vSphere-protected workloads.