feat: add cancel, pause, and resume flow control for scans

Users running large scans can now pause (keep partial results, resume
later), cancel (stop permanently, partial results preserved), or resume
a paused scan which races through cache hits before continuing.

Backend:
- Extend scans.status CHECK to include 'paused' and 'cancelled'
- Add _migrate_add_pause_cancel_status() table-recreation migration
- scan_processor: _running_tasks/_cancel_reasons registries,
  cancel_scan_task/pause_scan_task/stop_scan_task helpers,
  CancelledError handler in process_scan(), start_resume_processor()
- api_server: POST /scans/{id}/pause|cancel|resume endpoints with
  rate limits (30/min pause+cancel, 10/min resume); list_scans now
  accepts paused/cancelled as status filter values

Frontend:
- Scan.status type extended with 'paused' | 'cancelled'
- scanApi.pause/cancel/resume added
- StatusChip: amber PauseCircle chip for paused, grey Ban for cancelled
- ScanDetails: context-aware action row with inline-confirm for
  Pause and Cancel; Resume button for paused scans

Tests: 129 total (58 new) across test_scan_control.py,
test_scan_processor_control.py, and additions to existing suites

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

flight-comparator/frontend/src/pages/ScanDetails.tsx

@@ -8,6 +8,7 @@ import {
   Users,
   Armchair,
   Clock,
+  Timer,
   ChevronRight,
   ChevronUp,
   ChevronDown,
@@ -17,6 +18,9 @@ import {
   RotateCcw,
   Trash2,
   Info,
+  Pause,
+  Play,
+  X,
 } from 'lucide-react';
 import { scanApi } from '../api';
 import type { Scan, Route, Flight } from '../api';
@@ -25,6 +29,8 @@ import type { ScanStatus } from '../components/StatusChip';
 import StatCard from '../components/StatCard';
 import EmptyState from '../components/EmptyState';
 import { SkeletonStatCard, SkeletonTableRow } from '../components/SkeletonCard';
+import ScanTimer, { formatDuration } from '../components/ScanTimer';
+import { useScanTimer } from '../hooks/useScanTimer';
 import { cn } from '../lib/utils';
 
 const formatPrice = (price?: number) =>
@@ -52,6 +58,13 @@ export default function ScanDetails() {
   const [rerunning, setRerunning]           = useState(false);
   const [confirmDelete, setConfirmDelete]   = useState(false);
   const [deleting, setDeleting]             = useState(false);
+  const [confirmPause, setConfirmPause]     = useState(false);
+  const [confirmCancel, setConfirmCancel]   = useState(false);
+  const [stopping, setStopping]             = useState(false);
+  const [resuming, setResuming]             = useState(false);
+
+  // Must be called unconditionally before any early returns (Rules of Hooks)
+  const timer = useScanTimer(scan);
 
   useEffect(() => {
     if (id) loadScanDetails();
@@ -156,6 +169,47 @@ export default function ScanDetails() {
     }
   };
 
+  const handlePause = async () => {
+    if (!scan) return;
+    setStopping(true);
+    try {
+      await scanApi.pause(scan.id);
+      await loadScanDetails();
+    } catch {
+      // fall through
+    } finally {
+      setStopping(false);
+      setConfirmPause(false);
+    }
+  };
+
+  const handleCancel = async () => {
+    if (!scan) return;
+    setStopping(true);
+    try {
+      await scanApi.cancel(scan.id);
+      await loadScanDetails();
+    } catch {
+      // fall through
+    } finally {
+      setStopping(false);
+      setConfirmCancel(false);
+    }
+  };
+
+  const handleResume = async () => {
+    if (!scan) return;
+    setResuming(true);
+    try {
+      await scanApi.resume(scan.id);
+      await loadScanDetails();
+    } catch {
+      // fall through
+    } finally {
+      setResuming(false);
+    }
+  };
+
   const SortIcon = ({ field }: { field: typeof sortField }) => {
     if (sortField !== field) return <ChevronUp size={14} className="opacity-30" />;
     return sortDirection === 'asc'
@@ -261,51 +315,168 @@ export default function ScanDetails() {
         )}
 
         {/* Row 4: actions */}
-        <div className="mt-4 pt-4 border-t border-outline flex items-center justify-end gap-2">
-          {/* Re-run */}
-          <button
-            onClick={handleRerun}
-            disabled={rerunning || isActive}
-            className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
-          >
-            <RotateCcw size={14} className={rerunning ? 'animate-spin' : ''} />
-            {rerunning ? 'Starting…' : 'Re-run'}
-          </button>
+        <div className="mt-4 pt-4 border-t border-outline flex items-center justify-end gap-2 flex-wrap">
 
-          {/* Delete — inline confirm */}
-          {confirmDelete ? (
-            <div className="inline-flex items-center gap-1.5">
-              <span className="text-sm text-on-surface-variant">Delete this scan?</span>
+          {/* ── Active (pending / running): Pause + Cancel ── */}
+          {isActive && (
+            <>
+              {/* Pause — inline confirm */}
+              {confirmPause ? (
+                <div className="inline-flex items-center gap-1.5">
+                  <span className="text-sm text-on-surface-variant">Pause this scan?</span>
+                  <button
+                    onClick={handlePause}
+                    disabled={stopping}
+                    className="inline-flex items-center gap-1 px-3 py-1.5 text-sm font-medium rounded-xs bg-[#7A5200] text-white hover:bg-[#5C3D00] disabled:opacity-60 transition-colors"
+                  >
+                    {stopping ? 'Pausing…' : 'Yes, pause'}
+                  </button>
+                  <button
+                    onClick={() => setConfirmPause(false)}
+                    disabled={stopping}
+                    className="px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                  >
+                    No
+                  </button>
+                </div>
+              ) : (
+                <button
+                  onClick={() => setConfirmPause(true)}
+                  className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                >
+                  <Pause size={14} />
+                  Pause
+                </button>
+              )}
+
+              {/* Cancel — inline confirm */}
+              {confirmCancel ? (
+                <div className="inline-flex items-center gap-1.5">
+                  <span className="text-sm text-on-surface-variant">Cancel this scan?</span>
+                  <button
+                    onClick={handleCancel}
+                    disabled={stopping}
+                    className="inline-flex items-center gap-1 px-3 py-1.5 text-sm font-medium rounded-xs bg-error text-white hover:bg-error/90 disabled:opacity-60 transition-colors"
+                  >
+                    {stopping ? 'Cancelling…' : 'Yes, cancel'}
+                  </button>
+                  <button
+                    onClick={() => setConfirmCancel(false)}
+                    disabled={stopping}
+                    className="px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                  >
+                    No
+                  </button>
+                </div>
+              ) : (
+                <button
+                  onClick={() => setConfirmCancel(true)}
+                  className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-error/40 text-error hover:bg-error/5 transition-colors"
+                >
+                  <X size={14} />
+                  Cancel
+                </button>
+              )}
+            </>
+          )}
+
+          {/* ── Paused: Resume + Re-run + Delete ── */}
+          {scan.status === 'paused' && (
+            <>
               <button
-                onClick={handleDelete}
-                disabled={deleting}
-                className="inline-flex items-center gap-1 px-3 py-1.5 text-sm font-medium rounded-xs bg-error text-white hover:bg-error/90 disabled:opacity-60 transition-colors"
+                onClick={handleResume}
+                disabled={resuming}
+                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
               >
-                {deleting ? 'Deleting…' : 'Yes, delete'}
+                <Play size={14} className={resuming ? 'animate-pulse' : ''} />
+                {resuming ? 'Resuming…' : 'Resume'}
               </button>
+
               <button
-                onClick={() => setConfirmDelete(false)}
-                disabled={deleting}
-                className="px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                onClick={handleRerun}
+                disabled={rerunning}
+                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
               >
-                Cancel
+                <RotateCcw size={14} className={rerunning ? 'animate-spin' : ''} />
+                {rerunning ? 'Starting…' : 'Re-run'}
               </button>
-            </div>
-          ) : (
-            <button
-              onClick={() => setConfirmDelete(true)}
-              disabled={isActive}
-              className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-error/40 text-error hover:bg-error/5 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
-            >
-              <Trash2 size={14} />
-              Delete
-            </button>
+
+              {confirmDelete ? (
+                <div className="inline-flex items-center gap-1.5">
+                  <span className="text-sm text-on-surface-variant">Delete this scan?</span>
+                  <button
+                    onClick={handleDelete}
+                    disabled={deleting}
+                    className="inline-flex items-center gap-1 px-3 py-1.5 text-sm font-medium rounded-xs bg-error text-white hover:bg-error/90 disabled:opacity-60 transition-colors"
+                  >
+                    {deleting ? 'Deleting…' : 'Yes, delete'}
+                  </button>
+                  <button
+                    onClick={() => setConfirmDelete(false)}
+                    disabled={deleting}
+                    className="px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                  >
+                    Cancel
+                  </button>
+                </div>
+              ) : (
+                <button
+                  onClick={() => setConfirmDelete(true)}
+                  className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-error/40 text-error hover:bg-error/5 transition-colors"
+                >
+                  <Trash2 size={14} />
+                  Delete
+                </button>
+              )}
+            </>
+          )}
+
+          {/* ── Completed / Failed / Cancelled: Re-run + Delete ── */}
+          {!isActive && scan.status !== 'paused' && (
+            <>
+              <button
+                onClick={handleRerun}
+                disabled={rerunning}
+                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+              >
+                <RotateCcw size={14} className={rerunning ? 'animate-spin' : ''} />
+                {rerunning ? 'Starting…' : 'Re-run'}
+              </button>
+
+              {confirmDelete ? (
+                <div className="inline-flex items-center gap-1.5">
+                  <span className="text-sm text-on-surface-variant">Delete this scan?</span>
+                  <button
+                    onClick={handleDelete}
+                    disabled={deleting}
+                    className="inline-flex items-center gap-1 px-3 py-1.5 text-sm font-medium rounded-xs bg-error text-white hover:bg-error/90 disabled:opacity-60 transition-colors"
+                  >
+                    {deleting ? 'Deleting…' : 'Yes, delete'}
+                  </button>
+                  <button
+                    onClick={() => setConfirmDelete(false)}
+                    disabled={deleting}
+                    className="px-3 py-1.5 text-sm font-medium rounded-xs border border-outline text-on-surface hover:bg-surface-2 transition-colors"
+                  >
+                    Cancel
+                  </button>
+                </div>
+              ) : (
+                <button
+                  onClick={() => setConfirmDelete(true)}
+                  className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-xs border border-error/40 text-error hover:bg-error/5 transition-colors"
+                >
+                  <Trash2 size={14} />
+                  Delete
+                </button>
+              )}
+            </>
           )}
         </div>
       </div>
 
       {/* ── Stat cards ────────────────────────────────────────────── */}
-      <div className="grid grid-cols-3 gap-3">
+      <div className={`grid gap-3 ${!isActive && scan.started_at && scan.completed_at ? 'grid-cols-4' : 'grid-cols-3'}`}>
         {loading ? (
           [0, 1, 2].map(i => <SkeletonStatCard key={i} />)
         ) : (
@@ -313,6 +484,14 @@ export default function ScanDetails() {
             <StatCard label="Total Routes"   value={scan.total_routes}   icon={MapPin}       variant="primary"   />
             <StatCard label="Routes Scanned" value={scan.routes_scanned} icon={ChevronDown}  variant="secondary" />
             <StatCard label="Flights Found"  value={scan.total_flights}  icon={PlaneTakeoff} variant="primary"   />
+            {!isActive && scan.started_at && scan.completed_at && (
+              <StatCard
+                label="Scan Duration"
+                value={formatDuration(timer.elapsedSeconds)}
+                icon={Timer}
+                variant="secondary"
+              />
+            )}
           </>
         )}
       </div>
@@ -340,6 +519,9 @@ export default function ScanDetails() {
           <p className="mt-2 text-xs text-on-surface-variant">
             {scan.routes_scanned} of {scan.total_routes > 0 ? scan.total_routes : '?'} routes · auto-refreshing every 3 s
           </p>
+          {scan.status === 'running' && scan.started_at && (
+            <ScanTimer {...timer} />
+          )}
         </div>
       )}