fix(engine): floor percentComplete at 0 so it stays in its documented 0-100 range (#6773)

packages/loopover-engine/src/loop-progress.ts

@@ -40,8 +40,12 @@ export type ProgressSnapshot = {
 /** Build a customer-facing progress snapshot from already-computed loop state (#4800). Pure. */
 export function buildProgressSnapshot(state: LoopProgressState): ProgressSnapshot {
   const maxIterations = state.maxIterations ?? null;
+  // Clamp BOTH ends (#6773): `iteration` is an unvalidated caller-supplied number, so a negative one (an
+  // upstream bookkeeping bug) would otherwise produce a negative percent, contradicting the documented 0-100.
   const percentComplete =
-    maxIterations !== null && maxIterations > 0 ? Math.min(100, Math.round((state.iteration / maxIterations) * 100)) : null;
+    maxIterations !== null && maxIterations > 0
+      ? Math.max(0, Math.min(100, Math.round((state.iteration / maxIterations) * 100)))
+      : null;
   return {
     phase: state.phase,
     status: state.status,

test/unit/loop-progress.test.ts

@@ -28,6 +28,13 @@ describe("buildProgressSnapshot (#4800)", () => {
     expect(buildProgressSnapshot(running({ iteration: 7, maxIterations: 5 })).percentComplete).toBe(100);
   });
 
+  it("REGRESSION (#6773): floors percent-complete at 0 for a negative iteration, never below the documented range", () => {
+    // `iteration` is an unvalidated caller-supplied number: an upstream bookkeeping bug producing a negative
+    // one must not surface as a negative percent (the upper bound was clamped, the lower one was not).
+    expect(buildProgressSnapshot(running({ iteration: -1, maxIterations: 5 })).percentComplete).toBe(0);
+    expect(buildProgressSnapshot(running({ iteration: -100, maxIterations: 5 })).percentComplete).toBe(0);
+  });
+
   it("defaults recent activity to empty and caps the tail at MAX_PROGRESS_ACTIVITY", () => {
     expect(buildProgressSnapshot(running()).recentActivity).toEqual([]); // omitted
     const many = Array.from({ length: MAX_PROGRESS_ACTIVITY + 4 }, (_, i) => ({ step: `s${i}` }));