simple-module-background-tasks 0.0.30__tar.gz → 0.0.32__tar.gz

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/.gitignore

@@ -63,3 +63,4 @@ Thumbs.db
 host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
+.verify/

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_background_tasks
-Version: 0.0.30
+Version: 0.0.32
 Summary: Celery + Redis task queue with admin UI for monitoring and retrying failed/stuck tasks
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,10 +23,10 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: celery[redis]>=5.4
 Requires-Dist: redis>=5
-Requires-Dist: simple-module-core==0.0.30
-Requires-Dist: simple-module-db==0.0.30
-Requires-Dist: simple-module-hosting==0.0.30
-Requires-Dist: simple-module-settings==0.0.30
+Requires-Dist: simple-module-core==0.0.32
+Requires-Dist: simple-module-db==0.0.32
+Requires-Dist: simple-module-hosting==0.0.32
+Requires-Dist: simple-module-settings==0.0.32
 Description-Content-Type: text/markdown
 
 # simple_module_background_tasks

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/contracts/schemas.py

@@ -13,7 +13,13 @@ from background_tasks.constants import TaskStatus
 
 
 class TaskExecutionListItem(SQLModel):
-    """Compact row for the admin listing table."""
+    """Compact row for the admin listing table.
+
+    Carries ``args``/``kwargs`` even though the table never renders them: the
+    retry confirm opens straight from a row and has to show the payload it is
+    about to re-enqueue. Re-running a bad payload just fails the same way, so
+    the operator needs to read it *before* confirming, not on a second page.
+    """
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -22,6 +28,8 @@ class TaskExecutionListItem(SQLModel):
     task_name: str
     status: TaskStatus
     queue: str
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
     retries: int
     worker: str | None = None
     queued_at: datetime | None = None

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/endpoints/views.py

@@ -23,12 +23,33 @@ router = APIRouter(dependencies=[Depends(RequiresPermission(PERM_VIEW))])
 PER_PAGE = 20
 
 
+async def _worker_presence(request: Request) -> dict[str, object]:
+    """Whether anything is actually able to run a task right now.
+
+    An executions table with no rows has two very different causes: nothing has
+    been enqueued yet, or a worker was never started and the queue is piling up
+    unattended. The empty state cannot tell an operator which without asking
+    the broker.
+
+    Polling costs one inspect timeout (~1s), so this is called only when the
+    unfiltered list is genuinely empty — the one moment the answer changes what
+    the screen should say. The normal path never pays for it.
+    """
+    celery = request.app.state.background_tasks.celery
+    snapshot = await asyncio.to_thread(WorkerInspector(celery).snapshot)
+    return {
+        "broker_reachable": snapshot.broker_reachable,
+        "worker_count": sum(1 for w in snapshot.workers if w.online),
+    }
+
+
 @router.get("/", response_model=None)
 async def index(
     inertia: InertiaDep,
+    request: Request,
     status: TaskStatus | None = Query(default=None),
     task_name: str = Query(default="", alias="q"),
-    page: int = Query(default=1, ge=1),
+    page: int = Query(default=1),
     service: BackgroundTaskService = Depends(get_background_task_service),
 ) -> InertiaResponse:
     response = await service.list(
@@ -37,10 +58,27 @@ async def index(
         page=page,
         per_page=PER_PAGE,
     )
+    # A filtered-empty list says nothing about the fleet, so don't pay to poll
+    # it: the screen already knows to blame the filter.
+    unfiltered_and_empty = response.total == 0 and not task_name and status is None
+    # `_worker_presence` polls the broker over a thread, not the DB session
+    # `status_counts` uses — the two don't share state, so run them
+    # concurrently instead of paying the ~1s inspect timeout serially on top
+    # of the count query.
+    if unfiltered_and_empty:
+        counts, presence = await asyncio.gather(
+            service.status_counts(task_name=task_name or None),
+            _worker_presence(request),
+        )
+    else:
+        counts = await service.status_counts(task_name=task_name or None)
+        presence = None
     return await inertia.render(
         "BackgroundTasks/Index",
         {
             "executions": [i.model_dump(mode="json") for i in response.items],
+            "status_counts": {s.value: counts.get(s.value, 0) for s in TaskStatus},
+            "worker_presence": presence,
             "pagination": {
                 "page": response.page,
                 "per_page": response.per_page,

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/locales/en.json

@@ -53,5 +53,24 @@
   "toasts": {
     "retried": "Task \"{name}\" re-enqueued",
     "retry_failed": "Failed to retry task"
+  },
+  "worker_health": {
+    "broker_unreachable_title": "Broker unreachable",
+    "broker_unreachable_detail": "Nothing can be queued or run until the broker is back. The counts below are the last state written to the database.",
+    "no_workers_title_one": "{count} task waiting, no worker running",
+    "no_workers_title_other": "{count} tasks waiting, no worker running",
+    "no_workers_detail": "The broker is up but nothing is consuming the queue, so this backlog will not move on its own.",
+    "view_workers": "View workers"
+  },
+  "tasks_empty": {
+    "filtered_title": "No tasks match these filters",
+    "filtered_description": "Executions exist outside the current search and status filter.",
+    "clear_filters": "Clear filters",
+    "broker_unreachable_title": "Can't reach the broker",
+    "broker_unreachable_description": "Nothing can be queued or executed until the broker is back. Tasks are not being lost — they are not being accepted.",
+    "no_workers_title": "No worker is running",
+    "no_workers_description": "The broker is up, but nothing is consuming the queue. Tasks enqueued now will wait rather than run.",
+    "healthy_title": "No task has run yet",
+    "healthy_description": "Registered tasks appear here the first time they execute."
   }
 }

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/module.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from fastapi import APIRouter
+from simple_module_core.audit_links import AuditLinkRegistry
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
@@ -69,6 +70,20 @@ class BackgroundTasksModule(ModuleBase):
     def register_permissions(self, registry: PermissionRegistry) -> None:
         registry.add_group(PERM_GROUP, [PERM_VIEW, PERM_MANAGE])
 
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        from simple_module_core.audit_links import AuditLink
+
+        from background_tasks.models import TaskExecution
+
+        registry.register(
+            AuditLink(
+                # Class name, not __tablename__ — see AuditLink.entity_type.
+                entity_type=TaskExecution.__name__,
+                url_template=f"{VIEW_PREFIX}/{{id}}",
+                label="Task execution",
+            )
+        )
+
     def register_menu_items(self, registry: MenuRegistry) -> None:
         registry.add(
             MenuItem(

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/pages/Detail.tsx

@@ -110,6 +110,9 @@ function Detail() {
                     Retry task
                   </Button>
                 }
+                taskName={execution.task_name}
+                args={execution.args ?? []}
+                kwargs={execution.kwargs ?? {}}
                 onConfirm={handleRetry}
               />
             )}

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/pages/Index.tsx

@@ -13,17 +13,19 @@ import {
 import {
   Table,
   TableBody,
-  TableCell,
   TableHead,
   TableHeader,
   TableRow,
 } from '@simple-module-py/ui/components/ui/table';
 import { usePermissions } from '@simple-module-py/ui/hooks/use-permissions';
 import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
-import { Activity, Search, ServerCog } from 'lucide-react';
-import { useEffect, useState } from 'react';
+import { Search, ServerCog } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
 import { ExecutionRow, statusLabel } from './components/ExecutionRow';
-import { STATUS_ORDER, VIEW_BASE } from './constants';
+import { type StatusCounts, StatusStrip } from './components/StatusStrip';
+import { TasksEmptyRow, type WorkerPresence } from './components/TasksEmpty';
+import { WorkerHealthBanner } from './components/WorkerHealthBanner';
+import { STATUS_ORDER, TASK_STATUS, VIEW_BASE } from './constants';
 import { type Execution, retryExecution } from './retry';
 
 interface Pagination {
@@ -36,8 +38,14 @@ interface Props {
   executions: Execution[];
   pagination: Pagination;
   filters: { status: string; task_name: string };
+  status_counts: StatusCounts;
+  /** Null unless the unfiltered list came back empty — see the index view. */
+  worker_presence: WorkerPresence | null;
 }
 
+/** Task, Status, Queue, Queued, Duration, Worker, Actions. */
+const COLUMN_COUNT = 7;
+
 const STATUS_ALL = '__all__';
 
 function pushFilters(filters: { status: string; task_name: string }, page: number): void {
@@ -53,6 +61,8 @@ function Index() {
     executions,
     pagination,
     filters: initialFilters,
+    status_counts: statusCounts,
+    worker_presence: workerPresence,
   } = usePage<{ props: Props }>().props as unknown as Props;
 
   const { can } = usePermissions();
@@ -61,10 +71,40 @@ function Index() {
   const [search, setSearch] = useState(initialFilters.task_name ?? '');
   const totalPages = Math.ceil(pagination.total / pagination.per_page);
   const statusValue = initialFilters.status || STATUS_ALL;
+  // Derived from the server-confirmed filters, not the live `search` input:
+  // `workerPresence` reflects the last committed request, so mixing it with
+  // unsubmitted local state would flash the wrong empty-state copy during the
+  // debounce window between a keystroke and the resulting navigation.
+  const isFiltered = !!(initialFilters.task_name ?? '') || statusValue !== STATUS_ALL;
+
+  // Work that is supposed to be moving. Counting `running` too is deliberate:
+  // a row stuck in "running" with no worker alive means the worker died holding
+  // it, which is exactly as wrong as an unattended queue.
+  const backlog =
+    (statusCounts?.[TASK_STATUS.PENDING] ?? 0) + (statusCounts?.[TASK_STATUS.RUNNING] ?? 0);
+
+  // Set right before an explicit clear resets `search`, so the debounce
+  // effect below — which would otherwise see `search` change and reschedule
+  // a navigation using the still-stale `statusValue` prop — skips that one
+  // run instead of re-applying the status filter `clearFilters` just cleared.
+  const skipNextDebounceRef = useRef(false);
+
+  function clearFilters() {
+    // Only arm the skip when resetting `search` will actually fire the
+    // effect — if the box is already empty the effect never runs for the
+    // clear, and an armed flag would swallow the user's next keystroke.
+    if (search !== '') skipNextDebounceRef.current = true;
+    setSearch('');
+    pushFilters({ status: STATUS_ALL, task_name: '' }, 1);
+  }
 
   // Debounce search: any change from the server-provided value kicks off a
   // page-1 navigation 300ms after the user stops typing.
   useEffect(() => {
+    if (skipNextDebounceRef.current) {
+      skipNextDebounceRef.current = false;
+      return;
+    }
     if (search === (initialFilters.task_name ?? '')) return;
     const timeout = setTimeout(
       () => pushFilters({ status: statusValue, task_name: search }, 1),
@@ -75,7 +115,9 @@ function Index() {
 
   async function handleRetry(execution: Execution) {
     const created = await retryExecution(execution);
-    if (created) router.reload({ only: ['executions', 'pagination'] });
+    // status_counts feeds the strip above the table — a retry moves a row out
+    // of "failed", so leaving it out of the reload leaves the tile lying.
+    if (created) router.reload({ only: ['executions', 'pagination', 'status_counts'] });
   }
 
   return (
@@ -85,6 +127,18 @@ function Index() {
         title="Background Tasks"
         description="Monitor task executions and retry failed or stuck jobs."
       >
+        <StatusStrip
+          counts={statusCounts ?? {}}
+          active={initialFilters.status ?? ''}
+          onSelect={(status) => pushFilters({ status, task_name: search }, 1)}
+        />
+
+        {/* `statusCounts` (and therefore `backlog`) is scoped to the active
+            search/status filter — a narrowed view can read zero backlog while
+            the real fleet-wide queue is still stuck, so only trust it as a
+            health signal when nothing is filtering it. */}
+        {!isFiltered && <WorkerHealthBanner backlog={backlog} />}
+
         <div className="mb-4 flex flex-col sm:flex-row items-stretch sm:items-center justify-between gap-3">
           <div className="relative flex-1 max-w-sm">
             <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
@@ -139,18 +193,12 @@ function Index() {
                 <ExecutionRow key={e.id} execution={e} canRetry={canRetry} onRetry={handleRetry} />
               ))}
               {executions.length === 0 && (
-                <TableRow>
-                  <TableCell colSpan={7} className="h-32 text-center">
-                    <div className="flex flex-col items-center gap-2 text-muted-foreground">
-                      <Activity className="size-8" />
-                      <p>
-                        {search
-                          ? `No tasks match "${search}"`
-                          : 'No task executions yet. Tasks appear here as soon as modules enqueue work.'}
-                      </p>
-                    </div>
-                  </TableCell>
-                </TableRow>
+                <TasksEmptyRow
+                  filtered={isFiltered}
+                  columnCount={COLUMN_COUNT}
+                  presence={workerPresence ?? null}
+                  onClear={clearFilters}
+                />
               )}
             </TableBody>
           </Table>

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/pages/Workers.tsx

@@ -4,8 +4,9 @@ import { Badge } from '@simple-module-py/ui/components/ui/badge';
 import { Button } from '@simple-module-py/ui/components/ui/button';
 import { Card } from '@simple-module-py/ui/components/ui/card';
 import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { ageOf, isStale, relativeAgeLabel } from '@simple-module-py/ui/lib/relative-time';
 import { ArrowLeft, RefreshCw, ServerCrash, ServerOff } from 'lucide-react';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { toast } from 'sonner';
 import { API_BASE, formatTs, VIEW_BASE, type WorkerInfo, type WorkerSnapshot } from './constants';
 
@@ -72,6 +73,19 @@ function Workers() {
   const [snapshot, setSnapshot] = useState<WorkerSnapshot>(initial);
   const [loading, setLoading] = useState(false);
 
+  // This page is a point-in-time poll that only updates when asked. Left open
+  // on a second monitor it keeps rendering a healthy fleet long after that
+  // fleet died — the one failure it exists to catch. Ticking a clock beside the
+  // reading is what makes the page admit it has gone cold; the poll itself
+  // stays manual, so nobody's open tab quietly hammers the broker.
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 5_000);
+    return () => clearInterval(id);
+  }, []);
+  const age = ageOf(snapshot.polled_at, now);
+  const stale = isStale(age);
+
   async function refresh() {
     setLoading(true);
     try {
@@ -80,6 +94,8 @@ function Workers() {
       });
       if (res.ok) {
         setSnapshot((await res.json()) as WorkerSnapshot);
+        // Don't wait up to a tick for the age to catch up with the new reading.
+        setNow(Date.now());
       } else {
         toast.error(`Failed to refresh workers (HTTP ${res.status})`);
       }
@@ -102,10 +118,23 @@ function Workers() {
             </Link>
           </Button>
           <div className="flex items-center gap-3">
-            <span className="text-xs text-muted-foreground">
-              Last updated {formatTs(snapshot.polled_at)}
+            <span
+              className={`text-xs ${stale ? 'text-amber-600' : 'text-muted-foreground'}`}
+              title={`Polled at ${formatTs(snapshot.polled_at)}`}
+            >
+              Updated {relativeAgeLabel(age)}
             </span>
-            <Button variant="outline" size="sm" onClick={refresh} disabled={loading}>
+            {stale && (
+              <Badge variant="outline" className="border-amber-300 bg-amber-50 text-amber-700">
+                Stale
+              </Badge>
+            )}
+            <Button
+              variant={stale ? 'default' : 'outline'}
+              size="sm"
+              onClick={refresh}
+              disabled={loading}
+            >
               <RefreshCw className={`mr-2 size-4 ${loading ? 'animate-spin' : ''}`} />
               Refresh
             </Button>

{simple_module_background_tasks-0.0.30 → simple_module_background_tasks-0.0.32}/background_tasks/pages/components/ExecutionRow.tsx

@@ -3,7 +3,7 @@ import { Badge } from '@simple-module-py/ui/components/ui/badge';
 import { Button } from '@simple-module-py/ui/components/ui/button';
 import { TableCell, TableRow } from '@simple-module-py/ui/components/ui/table';
 import { RefreshCcw } from 'lucide-react';
-import { RETRYABLE_STATUSES, STATUS_BADGE_VARIANT, VIEW_BASE } from '../constants';
+import { formatTs, RETRYABLE_STATUSES, STATUS_BADGE_VARIANT, VIEW_BASE } from '../constants';
 import type { Execution } from '../retry';
 import { RetryConfirmDialog } from './RetryConfirmDialog';
 
@@ -50,7 +50,7 @@ export function ExecutionRow({ execution, canRetry, onRetry }: Props) {
         {execution.queue}
       </TableCell>
       <TableCell className="hidden lg:table-cell text-sm text-muted-foreground">
-        {execution.queued_at ? new Date(execution.queued_at).toLocaleString() : '—'}
+        {formatTs(execution.queued_at)}
       </TableCell>
       <TableCell className="hidden sm:table-cell text-sm tabular-nums">
         {formatDuration(execution.started_at, execution.finished_at)}
@@ -66,6 +66,9 @@ export function ExecutionRow({ execution, canRetry, onRetry }: Props) {
                 <RefreshCcw />
               </Button>
             }
+            taskName={execution.task_name}
+            args={execution.args ?? []}
+            kwargs={execution.kwargs ?? {}}
             onConfirm={() => onRetry(execution)}
           />
         ) : (

simple_module_background_tasks-0.0.32/background_tasks/pages/components/RetryConfirmDialog.tsx

@@ -0,0 +1,81 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@simple-module-py/ui/components/ui/alert-dialog';
+import type { ReactNode } from 'react';
+import { useMemo } from 'react';
+
+interface Props {
+  trigger: ReactNode;
+  onConfirm: () => void;
+  taskName: string;
+  args: unknown[];
+  kwargs: Record<string, unknown>;
+}
+
+/** Pretty-print a payload, degrading to a marker rather than throwing on a cycle. */
+function format(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 1)?.replace(/\n\s*/g, ' ') ?? String(value);
+  } catch {
+    return '<unserialisable>';
+  }
+}
+
+export function RetryConfirmDialog({ trigger, onConfirm, taskName, args, kwargs }: Props) {
+  const hasArgs = args.length > 0;
+  const hasKwargs = Object.keys(kwargs).length > 0;
+  // One dialog is mounted per retryable row (up to a full page of them), so
+  // this is re-evaluated on every re-render of the row above it — memoize
+  // rather than re-stringify a payload that hasn't changed.
+  const formattedArgs = useMemo(() => (hasArgs ? format(args) : ''), [hasArgs, args]);
+  const formattedKwargs = useMemo(() => (hasKwargs ? format(kwargs) : ''), [hasKwargs, kwargs]);
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>{trigger}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Retry {taskName}?</AlertDialogTitle>
+          <AlertDialogDescription>
+            Queues a new execution with the same arguments. The original row stays as it is, kept
+            for history.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+
+        {/* The arguments are the whole question: a retry re-sends this exact
+            payload, so if it is what failed, retrying blind just fails again. */}
+        {hasArgs || hasKwargs ? (
+          <dl className="grid gap-1.5 rounded-md bg-muted/60 p-3 font-mono text-xs">
+            {hasArgs && (
+              <div className="flex gap-2">
+                <dt className="shrink-0 text-muted-foreground">args:</dt>
+                <dd className="min-w-0 break-all">{formattedArgs}</dd>
+              </div>
+            )}
+            {hasKwargs && (
+              <div className="flex gap-2">
+                <dt className="shrink-0 text-muted-foreground">kwargs:</dt>
+                <dd className="min-w-0 break-all">{formattedKwargs}</dd>
+              </div>
+            )}
+          </dl>
+        ) : (
+          <p className="text-xs text-muted-foreground">This task takes no arguments.</p>
+        )}
+
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Retry task</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

simple_module_background_tasks-0.0.32/background_tasks/pages/components/StatusStrip.tsx

@@ -0,0 +1,66 @@
+import { TASK_STATUS, type TaskStatus } from '../constants';
+import { statusLabel } from './ExecutionRow';
+
+export type StatusCounts = Partial<Record<TaskStatus, number>>;
+
+interface Props {
+  counts: StatusCounts;
+  /** Currently filtered status, or '' for all. */
+  active: string;
+  onSelect: (status: string) => void;
+}
+
+/**
+ * Statuses worth a dedicated tile, in the order an operator triages them.
+ * Failed and stuck lead because they are the reason anyone opens this page.
+ */
+const TILES: TaskStatus[] = [
+  TASK_STATUS.FAILED,
+  TASK_STATUS.STUCK,
+  TASK_STATUS.RETRYING,
+  TASK_STATUS.RUNNING,
+  TASK_STATUS.PENDING,
+  TASK_STATUS.SUCCESS,
+];
+
+/** Tiles that mean "someone needs to look at this" get an alarm colour, but
+ *  only when they are non-zero — a permanently red zero trains people to
+ *  ignore it. */
+const ALARMING = new Set<TaskStatus>([TASK_STATUS.FAILED, TASK_STATUS.STUCK]);
+
+export function StatusStrip({ counts, active, onSelect }: Props) {
+  return (
+    <div className="mb-4 grid grid-cols-3 gap-2 sm:grid-cols-6">
+      {TILES.map((status) => {
+        const count = counts[status] ?? 0;
+        const isActive = active === status;
+        const alarm = ALARMING.has(status) && count > 0;
+        return (
+          <button
+            key={status}
+            type="button"
+            aria-pressed={isActive}
+            // Clicking the tile you already filtered by clears the filter,
+            // so the strip can undo itself without reaching for the dropdown.
+            onClick={() => onSelect(isActive ? '' : status)}
+            className={[
+              'rounded-lg border px-3 py-2 text-left transition-colors',
+              isActive
+                ? 'border-primary bg-accent'
+                : 'border-border bg-card hover:border-primary/40 hover:bg-accent/50',
+            ].join(' ')}
+          >
+            <div
+              className={`text-lg font-semibold tabular-nums leading-tight ${
+                alarm ? 'text-red-600 dark:text-red-400' : 'text-foreground'
+              }`}
+            >
+              {count}
+            </div>
+            <div className="truncate text-[11px] text-muted-foreground">{statusLabel(status)}</div>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

simple_module_background_tasks-0.0.32/background_tasks/pages/components/TasksEmpty.tsx

@@ -0,0 +1,102 @@
+import { Link } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { EmptyState } from '@simple-module-py/ui/components/EmptyState';
+import { TableEmptyRow } from '@simple-module-py/ui/components/TableEmptyRow';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import type { TFunction } from 'i18next';
+import { Activity, type LucideIcon, PlugZap, ServerCog, ServerOff } from 'lucide-react';
+import { VIEW_BASE } from '../constants';
+import { diagnoseWorkerHealth } from '../worker-health';
+
+export interface WorkerPresence {
+  broker_reachable: boolean;
+  worker_count: number;
+}
+
+interface TasksEmptyRowProps {
+  /** A search term or status filter is narrowing the list. */
+  filtered: boolean;
+  columnCount: number;
+  /** Fleet state, polled by the server only when the unfiltered list is empty. */
+  presence: WorkerPresence | null;
+  onClear: () => void;
+}
+
+interface EmptyCopy {
+  icon: LucideIcon;
+  title: string;
+  description: string;
+}
+
+/**
+ * Which "nothing here" message the executions table should show.
+ *
+ * "No task has run yet" is reassuring and wrong when the real cause is that no
+ * worker was ever started: the queue is filling and nothing is draining it.
+ * These are three different operator problems, so they get three different
+ * messages. A filtered-empty list is handled by the caller — the fleet is not
+ * why those rows are missing.
+ */
+function emptyCopy(t: TFunction, presence: WorkerPresence | null): EmptyCopy {
+  const state = presence
+    ? diagnoseWorkerHealth({
+        brokerReachable: presence.broker_reachable,
+        onlineWorkerCount: presence.worker_count,
+      })
+    : 'healthy';
+  if (state === 'broker_unreachable') {
+    return {
+      icon: PlugZap,
+      title: t(keys.background_tasks.tasks_empty.broker_unreachable_title),
+      description: t(keys.background_tasks.tasks_empty.broker_unreachable_description),
+    };
+  }
+  if (state === 'no_workers_online') {
+    return {
+      icon: ServerOff,
+      title: t(keys.background_tasks.tasks_empty.no_workers_title),
+      description: t(keys.background_tasks.tasks_empty.no_workers_description),
+    };
+  }
+  return {
+    icon: Activity,
+    title: t(keys.background_tasks.tasks_empty.healthy_title),
+    description: t(keys.background_tasks.tasks_empty.healthy_description),
+  };
+}
+
+/** The executions table's empty row, in whichever of its four states applies. */
+export function TasksEmptyRow({ filtered, columnCount, presence, onClear }: TasksEmptyRowProps) {
+  const { t } = useT();
+  const copy = emptyCopy(t, presence);
+  return (
+    <TableEmptyRow columnCount={columnCount}>
+      {filtered ? (
+        <EmptyState
+          icon={Activity}
+          title={t(keys.background_tasks.tasks_empty.filtered_title)}
+          description={t(keys.background_tasks.tasks_empty.filtered_description)}
+          action={
+            <Button variant="outline" onClick={onClear}>
+              {t(keys.background_tasks.tasks_empty.clear_filters)}
+            </Button>
+          }
+        />
+      ) : (
+        <EmptyState
+          icon={copy.icon}
+          title={copy.title}
+          description={copy.description}
+          action={
+            <Button variant="outline" asChild>
+              <Link href={`${VIEW_BASE}/workers`}>
+                <ServerCog className="mr-2 size-4" />
+                {t(keys.background_tasks.worker_health.view_workers)}
+              </Link>
+            </Button>
+          }
+        />
+      )}
+    </TableEmptyRow>
+  );
+}