K2GO-386 refactor(app-backstop): extract pure escalation rule; guard reap; fix debug/report

Second code-review pass on L3b. Five fixes.

1. Deep-op guard. DiskGuard.deepOpActive(ctx) reads EnvironmentLock.currentHolder.
   If a STOPPED-class op (clone, backup, restore, install) holds the box, the tick
   logs and returns without reaping. A reap mid-extract would corrupt the rootfs.

2. Debug path no longer escalates. checkWithFloor runs in FORCED mode. FORCED always
   CONTAINs. It never advances the trip state. Before, three debug triggers could stop
   the box.

3. Consecutive-trip semantics. A non-critical tick ends the spell and resets the count.
   Escalation now means the disk stayed critical across consecutive restarts, so the
   restart is not fixing it. Before, the count reset only on a 30-min gap or app restart.

4. Testable escalation. The decision moves to the pure DiskGuardEscalation.next(...).
   No android.* imports. DiskGuardEscalationTest covers five cases on a plain JVM.

5. Report cadence. A CONTAIN reports only on the first trip of a spell. An ESCALATE
   always reports. A thrash no longer enqueues one analytics event per trip.

See controller/docs/ADR-386-unattended-disk-containment.md.

Author: luisguzman-adfa

controller/app/src/main/java/org/appdevforall/k2go/diskguard/DiskGuard.java

@@ -8,14 +8,17 @@
  *
  *               One tick reads free space (StorageProbe) and asks the pure rule
  *               (DiskGuardPolicy). On CRITICAL it CONFIRMS with a fresh re-read
- *               (it never acts on one reading), then reaps the box and reclaims
- *               the runaway log. The default action KEEPS THE SYSTEM ALIVE: it
- *               does not force the server down. A fresh service under a fresh
- *               proot does not busy-loop, so the ADFA-5343 reconciler relaunches
- *               a clean box. Only when the fill KEEPS RETURNING after several
- *               restarts in a window does the guard stop and stay down as a last
- *               resort, and tell the user. Every trip is reported to developers
- *               through the delivery backbone.
+ *               (it never acts on one reading). It does NOT reap while a deep op
+ *               (clone/backup/restore/install) holds the box, because a reap
+ *               mid-operation would corrupt it. Otherwise it reaps the box and
+ *               reclaims the runaway log.
+ *
+ *               The default action KEEPS THE SYSTEM ALIVE: it does not force the
+ *               server down. A fresh service under a fresh proot does not
+ *               busy-loop, so the ADFA-5343 reconciler relaunches a clean box.
+ *               Only when the disk stays critical for several trips in a row
+ *               (DiskGuardEscalation) does the guard stop and stay down as a last
+ *               resort and tell the user. Trips are reported to developers.
  *
  *               Why Android-side: the fill happens when the box proot dies and a
  *               service is orphaned off proot. An in-box kill does not reach the
@@ -38,10 +41,13 @@
 
 import org.appdevforall.k2go.R;
 import org.appdevforall.k2go.delivery.DeliveryManager;
+import org.appdevforall.k2go.diskguard.domain.DiskGuardEscalation;
 import org.appdevforall.k2go.diskguard.domain.DiskGuardPolicy;
+import org.appdevforall.k2go.env.EnvironmentLock;
 import org.appdevforall.k2go.env.EnvironmentProcess;
 import org.appdevforall.k2go.env.ServerLifecycleReconciler;
 import org.appdevforall.k2go.storage.StorageProbe;
+import org.appdevforall.k2go.system.domain.Operation;
 
 import org.json.JSONObject;
 
@@ -60,16 +66,16 @@ public final class DiskGuard {
     // a momentary spike does not (ADR-386, "confirm before acting").
     private static final long CONFIRM_DELAY_MS = 1000L;
 
-    // Restart-to-keep-alive is the default. If the fill returns this many times inside TRIP_WINDOW_MS,
-    // the restart is not fixing it, so the guard escalates to stop-and-stay-down as a last resort.
+    // Restart-to-keep-alive is the default. If the disk stays critical this many trips in a row, the
+    // restart is not fixing it, so the guard escalates to stop-and-stay-down as a last resort.
     private static final int ESCALATE_AFTER_TRIPS = 3;
     private static final long TRIP_WINDOW_MS = 30L * 60L * 1000L;
 
     private static final String CHANNEL_ID = "disk_guard_channel";
     private static final int NOTIF_ID = 7386;
 
     // Recent-trip state, in memory on purpose: it resets when the app process restarts, so a stale count
-    // never carries across a restart. Guarded by the class monitor.
+    // never carries across a restart. Read and written only under advanceTripState (class monitor).
     private static long lastTripElapsedMs = -1L;
     private static int tripCount = 0;
 
@@ -80,36 +86,57 @@ private DiskGuard() {}
      * repeatedly from a poller. A null or UNKNOWN read is a no-op.
      */
     public static boolean check(Context ctx) {
-        return checkWithFloor(ctx, DiskGuardPolicy.CRITICAL_FLOOR_BYTES);
+        return run(ctx, DiskGuardPolicy.CRITICAL_FLOOR_BYTES, false);
     }
 
     /**
-     * As {@link #check} but with an explicit floor. The debug device-verify hook passes a huge floor so
-     * any real free-space read is CRITICAL. This forces the action without filling the disk for real.
+     * The debug device-verify hook. It passes a huge floor so any real free-space read is CRITICAL, and
+     * runs in FORCED mode: it exercises the reap/reclaim/restart path once but does NOT advance the real
+     * escalation count, so triggering it repeatedly cannot stop the box.
      */
     public static boolean checkWithFloor(Context ctx, long floorBytes) {
+        return run(ctx, floorBytes, true);
+    }
+
+    private static boolean run(Context ctx, long floorBytes, boolean forced) {
         if (ctx == null) return false;
-        if (!confirmCritical(ctx, floorBytes)) return false;
+        boolean critical = confirmCritical(ctx, floorBytes);
+
+        DiskGuardEscalation.Verdict v;
+        if (forced) {
+            // Forced (debug): CONTAIN if critical, and never touch the shared trip state or escalate.
+            v = new DiskGuardEscalation.Verdict(
+                    critical ? DiskGuardEscalation.Action.CONTAIN : DiskGuardEscalation.Action.NONE,
+                    0, 0L, true);
+        } else {
+            v = advanceTripState(critical);
+        }
+        if (v.action == DiskGuardEscalation.Action.NONE) return false;
+
+        // Never reap while a deep op owns the box (clone/backup/restore/install). A reap mid-operation
+        // would corrupt it. EnvironmentLock is the one owner of "is a stop-class op running".
+        if (deepOpActive(ctx)) {
+            Log.w(TAG, "K2GO-386: disk critical but a deep op holds the box; not reaping this tick");
+            return false;
+        }
 
-        int trip = recordTrip();
         boolean reaped = EnvironmentProcess.reapBox(ctx);
         long reclaimed = reclaimRunawayLog(ctx);
 
-        if (trip < ESCALATE_AFTER_TRIPS) {
-            // Default: keep the system alive. Do NOT force desired=DOWN. The reconciler (ADFA-5343) owns
-            // "should the box be up"; it is left UP, so it relaunches a fresh box. Ask it to act now
-            // instead of on its next tick.
-            ServerLifecycleReconciler.get().requestReconcileNow();
-            report(ctx, "contained", floorBytes, reaped, reclaimed, trip);
-            Log.w(TAG, "K2GO-386: contained disk pressure (trip " + trip + "): reaped=" + reaped
-                    + ", reclaimed=" + reclaimed + " B, box restarting");
-        } else {
+        if (v.action == DiskGuardEscalation.Action.ESCALATE) {
             // Last resort: the fill keeps returning after restarts. Stop and stay down through the one
             // persisted lever, and tell the user. The user re-enables the server after freeing space.
             ServerLifecycleReconciler.get().setUserWantsOn(ctx, false);
             notifyUser(ctx);
-            report(ctx, "escalated_stopped", floorBytes, reaped, reclaimed, trip);
-            Log.w(TAG, "K2GO-386: recurring disk pressure (trip " + trip + "): stopped and staying down");
+            report(ctx, "escalated_stopped", floorBytes, reaped, reclaimed, v.tripCount);
+            Log.w(TAG, "K2GO-386: recurring disk pressure (trip " + v.tripCount + "): stopped and staying down");
+        } else {
+            // Default: keep the system alive. Leave desired=UP and ask the reconciler to relaunch a fresh
+            // box now. Report only the first trip of a spell so a thrash does not spam telemetry.
+            ServerLifecycleReconciler.get().requestReconcileNow();
+            if (v.firstOfSpell) report(ctx, "contained", floorBytes, reaped, reclaimed, v.tripCount);
+            Log.w(TAG, "K2GO-386: contained disk pressure (trip " + v.tripCount + "): reaped=" + reaped
+                    + ", reclaimed=" + reclaimed + " B, box restarting");
         }
         return true;
     }
@@ -135,14 +162,19 @@ private static boolean confirmCritical(Context ctx, long floorBytes) {
         return stillCritical;
     }
 
-    /** Count trips inside a sliding window. Returns the trip number in the current window (1-based). */
-    private static synchronized int recordTrip() {
-        long now = SystemClock.elapsedRealtime();
-        if (lastTripElapsedMs < 0L || now - lastTripElapsedMs > TRIP_WINDOW_MS) {
-            tripCount = 0;
-        }
-        lastTripElapsedMs = now;
-        return ++tripCount;
+    /** Advance the shared trip state with the pure rule and return the verdict. */
+    private static synchronized DiskGuardEscalation.Verdict advanceTripState(boolean critical) {
+        DiskGuardEscalation.Verdict v = DiskGuardEscalation.next(
+                critical, SystemClock.elapsedRealtime(), lastTripElapsedMs, tripCount,
+                TRIP_WINDOW_MS, ESCALATE_AFTER_TRIPS);
+        tripCount = v.tripCount;
+        lastTripElapsedMs = v.lastElapsedMs;
+        return v;
+    }
+
+    /** True when a stop-class operation (clone/backup/restore/install) currently holds the box. */
+    private static boolean deepOpActive(Context ctx) {
+        return EnvironmentLock.currentHolder(ctx).executionClass == Operation.ExecutionClass.STOPPED;
     }
 
     /** Report the event to developers through the delivery backbone (unattended; not user-facing). */

controller/app/src/main/java/org/appdevforall/k2go/diskguard/domain/DiskGuardEscalation.java

@@ -0,0 +1,64 @@
+/*
+ * ============================================================================
+ * Name        : DiskGuardEscalation.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : K2GO-386 (Layer 3). The pure escalation rule for the app-side
+ *               disk-fill backstop. It decides, on one guard tick, what to do
+ *               from whether the disk is critical now plus the recent-trip state.
+ *               No android.*, so it is unit-tested on a plain JVM. See ADR-386.
+ * ============================================================================
+ */
+package org.appdevforall.k2go.diskguard.domain;
+
+/**
+ * A trip is a confirmed-critical tick. Trips count only while they stay CONSECUTIVE: a non-critical tick
+ * ends the spell and resets the count, and a long gap (over the window) resets it too. The default action
+ * is CONTAIN (reap, then let the box restart). If the disk stays critical for {@code escalateAfter} trips
+ * in a row, the restart is not fixing it, so the action becomes ESCALATE (stop and stay down).
+ */
+public final class DiskGuardEscalation {
+
+    public enum Action { NONE, CONTAIN, ESCALATE }
+
+    /** The new trip state plus the action to take. Immutable. */
+    public static final class Verdict {
+        public final Action action;
+        public final int tripCount;       // new consecutive-trip count; 0 when not critical
+        public final long lastElapsedMs;  // new last-trip time
+        public final boolean firstOfSpell; // tripCount == 1; used to report once per spell
+
+        public Verdict(Action action, int tripCount, long lastElapsedMs, boolean firstOfSpell) {
+            this.action = action;
+            this.tripCount = tripCount;
+            this.lastElapsedMs = lastElapsedMs;
+            this.firstOfSpell = firstOfSpell;
+        }
+    }
+
+    private DiskGuardEscalation() {}
+
+    /**
+     * @param critical      whether the disk is critical on this tick (already confirmed).
+     * @param nowMs         a monotonic clock reading (SystemClock.elapsedRealtime).
+     * @param lastElapsedMs the previous trip's clock reading, or negative if none.
+     * @param prevCount     the previous consecutive-trip count.
+     * @param windowMs      a gap longer than this starts a new spell.
+     * @param escalateAfter the trip number at which to escalate.
+     */
+    public static Verdict next(boolean critical, long nowMs, long lastElapsedMs, int prevCount,
+                               long windowMs, int escalateAfter) {
+        if (!critical) {
+            // The disk recovered. End the spell so a later, separate fill starts fresh.
+            return new Verdict(Action.NONE, 0, lastElapsedMs, false);
+        }
+        int count;
+        if (prevCount <= 0 || lastElapsedMs < 0L || nowMs - lastElapsedMs > windowMs) {
+            count = 1; // first trip of a new spell
+        } else {
+            count = prevCount + 1;
+        }
+        Action action = count >= escalateAfter ? Action.ESCALATE : Action.CONTAIN;
+        return new Verdict(action, count, nowMs, count == 1);
+    }
+}

controller/app/src/test/java/org/appdevforall/k2go/diskguard/domain/DiskGuardEscalationTest.java

@@ -0,0 +1,55 @@
+package org.appdevforall.k2go.diskguard.domain;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import org.appdevforall.k2go.diskguard.domain.DiskGuardEscalation.Action;
+import org.appdevforall.k2go.diskguard.domain.DiskGuardEscalation.Verdict;
+
+import org.junit.Test;
+
+public class DiskGuardEscalationTest {
+
+    private static final long WINDOW = 30L * 60L * 1000L;
+    private static final int ESCALATE = 3;
+
+    @Test
+    public void notCritical_isNoneAndResetsCount() {
+        Verdict v = DiskGuardEscalation.next(false, 1000L, 500L, 2, WINDOW, ESCALATE);
+        assertEquals(Action.NONE, v.action);
+        assertEquals(0, v.tripCount);
+    }
+
+    @Test
+    public void firstCritical_isContainTripOne() {
+        Verdict v = DiskGuardEscalation.next(true, 1000L, -1L, 0, WINDOW, ESCALATE);
+        assertEquals(Action.CONTAIN, v.action);
+        assertEquals(1, v.tripCount);
+        assertTrue(v.firstOfSpell);
+    }
+
+    @Test
+    public void consecutiveCritical_incrementsWithinWindow() {
+        Verdict v = DiskGuardEscalation.next(true, 2000L, 1000L, 1, WINDOW, ESCALATE);
+        assertEquals(Action.CONTAIN, v.action);
+        assertEquals(2, v.tripCount);
+        assertFalse(v.firstOfSpell);
+    }
+
+    @Test
+    public void escalatesAtThreshold() {
+        Verdict v = DiskGuardEscalation.next(true, 3000L, 2000L, 2, WINDOW, ESCALATE);
+        assertEquals(Action.ESCALATE, v.action);
+        assertEquals(3, v.tripCount);
+    }
+
+    @Test
+    public void gapBeyondWindow_startsNewSpell() {
+        // prevCount is 2, but the gap exceeds the window, so the spell resets to trip 1.
+        Verdict v = DiskGuardEscalation.next(true, 100_000_000L, 1000L, 2, WINDOW, ESCALATE);
+        assertEquals(Action.CONTAIN, v.action);
+        assertEquals(1, v.tripCount);
+        assertTrue(v.firstOfSpell);
+    }
+}