fix(webapp,run-engine): clear stale metric rows on query change, document override cap

Address review findings on the queue metrics PR:

- useMetricResourceQuery kept the previous query's rows when the signature
  changed with no cache entry for the new key, so showLoading (isLoading &&
  !rows) stayed false and a chart painted the old time range as if it were the
  new one. A stale `failed` also survived, rendering an "invalid" chart state
  over a healthy new query. Reset both when the signature actually changes;
  interval and on-focus refreshes reuse the signature and are unaffected.
- Document in the OpenAPI spec that the queue concurrency override rejects
  limits above the environment maximum with a 400 instead of capping them.
- Correct the enqueueSystem TTL comment: the pending-version promotion does
  pass includeTtl, so it is not in the "must not add TTL" set.

Author: samejr

apps/webapp/app/hooks/useMetricResourceQuery.ts

@@ -83,14 +83,21 @@ export function useMetricResourceQuery(query: string, opts: MetricResourceQueryO
   const [isLoading, setIsLoading] = useState(true);
   const [failed, setFailed] = useState(false);
   const abortRef = useRef<AbortController | null>(null);
+  const loadedKeyRef = useRef<string | null>(null);
 
   const load = useCallback(() => {
     abortRef.current?.abort();
     const controller = new AbortController();
     abortRef.current = controller;
-    // Paint cached rows immediately (no skeleton) on remount / key change while we revalidate.
-    const cached = responseCache.get(cacheKey);
-    if (cached) setRows(cached);
+    // On a new query signature the rows and failure on screen belong to a different query. Paint
+    // this key's cached rows if we have them (no skeleton on remount / back-navigation), otherwise
+    // clear them so a genuinely new query shows a loading state instead of another query's data.
+    // Interval and on-focus refreshes reuse the same signature, so they keep what's on screen.
+    if (loadedKeyRef.current !== cacheKey) {
+      loadedKeyRef.current = cacheKey;
+      setRows(responseCache.get(cacheKey) ?? null);
+      setFailed(false);
+    }
     setIsLoading(true);
     fetch("/resources/metric", {
       method: "POST",

docs/v3-openapi.yaml

@@ -3001,7 +3001,10 @@ paths:
                   type: integer
                   minimum: 0
                   maximum: 100000
-                  description: The new concurrency limit to set for the queue
+                  description: |
+                    The new concurrency limit to set for the queue. It may not exceed your
+                    environment's maximum concurrency limit: a higher value is rejected with a
+                    400, not capped to the maximum.
       responses:
         "200":
           description: Concurrency limit overridden successfully
@@ -3010,7 +3013,9 @@ paths:
               schema:
                 "$ref": "#/components/schemas/QueueObject"
         "400":
-          description: Invalid request parameters
+          description: |
+            Invalid request parameters, or the requested concurrency limit exceeds the
+            environment's maximum concurrency limit.
         "401":
           description: Unauthorized request
         "404":

internal-packages/run-engine/src/engine/systems/enqueueSystem.ts

@@ -105,9 +105,9 @@ export class EnqueueSystem {
       const timestamp = queuePositionMs - run.priorityMs;
       const eligibleAtMs = includeTtl ? queuePositionMs : Date.now();
 
-      // Include TTL only when explicitly requested (first enqueue from trigger or the
-      // delayed-run system). Re-enqueues (waitpoint, checkpoint, pending version) must
-      // not add TTL.
+      // Include TTL only when explicitly requested: the first enqueue from trigger, the
+      // delayed-run system, and the pending-version promotion (each is a run's first real
+      // entry into the queue). Waitpoint and checkpoint re-enqueues must not add TTL.
       let ttlExpiresAt: number | undefined;
       if (includeTtl && run.ttl) {
         const expireAt = parseNaturalLanguageDuration(run.ttl);