python-pq 0.1.1__tar.gz → 0.1.4__tar.gz

{python_pq-0.1.1 → python_pq-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-pq
-Version: 0.1.1
+Version: 0.1.4
 Summary: Postgres-backed job queue for Python
 Author: ricwo
 Author-email: ricwo <r@cogram.com>
@@ -13,21 +13,26 @@ Requires-Dist: psycopg2-binary>=2.9.11
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydantic-settings>=2.12.0
 Requires-Dist: sqlalchemy>=2.0.45
-Requires-Python: >=3.14
+Requires-Dist: mkdocs-material>=9.6 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.29 ; extra == 'docs'
+Requires-Python: >=3.13, <3.15
+Provides-Extra: docs
 Description-Content-Type: text/markdown
 
 # pq
 
 Postgres-backed job queue for Python with fork-based worker isolation.
 
+**[Documentation](https://ricwo.github.io/pq/)**
+
 ## Features
 
 - **Fork isolation** - Each task runs in a forked process. OOM or crashes don't affect the worker.
-- **Natural Python API** - Pass `*args, **kwargs` directly. Pydantic models and custom objects work.
+- **Natural Python API** - Pass functions directly with `*args, **kwargs`.
 - **Periodic tasks** - Schedule with intervals or cron expressions.
-- **Priority queues** - Five priority levels, higher priority tasks run first.
+- **Priority queues** - Five levels, higher priority tasks run first.
 - **Async support** - Async handlers work seamlessly.
-- **Concurrent workers** - Multiple workers with `FOR UPDATE SKIP LOCKED` prevents duplicate processing.
+- **Concurrent workers** - `FOR UPDATE SKIP LOCKED` prevents duplicate processing.
 
 ## Installation
 
@@ -35,7 +40,7 @@ Postgres-backed job queue for Python with fork-based worker isolation.
 uv add pq
 ```
 
-Requires PostgreSQL and Python 3.14+.
+Requires PostgreSQL and Python 3.13+.
 
 ## Quick Start
 
@@ -45,14 +50,16 @@ from pq import PQ
 pq = PQ("postgresql://localhost/mydb")
 pq.create_tables()
 
-def send_email(to: str, subject: str, body: str) -> None:
-    print(f"Sending email to {to}: {subject}")
+def send_email(to: str, subject: str) -> None:
+    print(f"Sending to {to}: {subject}")
 
-pq.enqueue(send_email, to="user@example.com", subject="Hello", body="...")
+pq.enqueue(send_email, to="user@example.com", subject="Hello")
 pq.run_worker()
 ```
 
-## Enqueueing Tasks
+## Tasks
+
+### Enqueueing
 
 ```python
 def greet(name: str) -> None:
@@ -60,45 +67,108 @@ def greet(name: str) -> None:
 
 pq.enqueue(greet, name="World")
 pq.enqueue(greet, "World")  # Positional args work too
+```
+
+### Delayed Execution
 
-# Delayed execution
+```python
 from datetime import datetime, timedelta, UTC
+
 pq.enqueue(greet, "World", run_at=datetime.now(UTC) + timedelta(hours=1))
+```
 
-# Priority
+### Priority
+
+```python
 from pq import Priority
-pq.enqueue(greet, "World", priority=Priority.CRITICAL)  # 100
-pq.enqueue(greet, "World", priority=Priority.HIGH)      # 75
-pq.enqueue(greet, "World", priority=Priority.NORMAL)    # 50 (default)
-pq.enqueue(greet, "World", priority=Priority.LOW)       # 25
-pq.enqueue(greet, "World", priority=Priority.BATCH)     # 0
+
+pq.enqueue(task, priority=Priority.CRITICAL)  # 100 - highest
+pq.enqueue(task, priority=Priority.HIGH)      # 75
+pq.enqueue(task, priority=Priority.NORMAL)    # 50 (default)
+pq.enqueue(task, priority=Priority.LOW)       # 25
+pq.enqueue(task, priority=Priority.BATCH)     # 0 - lowest
+```
+
+### Cancellation
+
+```python
+task_id = pq.enqueue(my_task)
+pq.cancel(task_id)  # Returns True if found and cancelled
 ```
 
 ## Periodic Tasks
 
+### Intervals
+
 ```python
 from datetime import timedelta
 
 def heartbeat() -> None:
     print("alive")
 
+pq.schedule(heartbeat, run_every=timedelta(minutes=5))
+```
+
+### Cron Expressions
+
+```python
 def weekly_report() -> None:
     print("generating report...")
 
-# Fixed interval
-pq.schedule(heartbeat, run_every=timedelta(minutes=5))
-
-# Cron expression (Monday 9am)
-pq.schedule(weekly_report, cron="0 9 * * 1")
+pq.schedule(weekly_report, cron="0 9 * * 1")  # Monday 9am
+```
 
-# With arguments
-def report(report_type: str) -> None:
-    print(f"generating {report_type} report...")
+### With Arguments
 
+```python
 pq.schedule(report, run_every=timedelta(hours=1), report_type="hourly")
+```
+
+### Unscheduling
+
+```python
+pq.unschedule(heartbeat)  # Returns True if found
+```
+
+## Workers
+
+### Running
+
+```python
+# Run forever, poll every second when idle
+pq.run_worker(poll_interval=1.0)
+
+# Process single task (for testing)
+processed = pq.run_worker_once()
+```
+
+### Timeout
+
+Kill tasks that run too long:
+
+```python
+pq.run_worker(max_runtime=300)  # 5 minute timeout
+```
+
+### Priority-Dedicated Workers
+
+Reserve workers for high-priority tasks:
+
+```python
+from pq import Priority
+
+# This worker only processes CRITICAL and HIGH
+pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})
+```
+
+Run multiple workers in separate terminals:
+
+```bash
+# Terminal 1: High-priority only
+python -c "from myapp import pq; from pq import Priority; pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})"
 
-# Remove schedule
-pq.unschedule(heartbeat)
+# Terminal 2-3: All priorities
+python -c "from myapp import pq; pq.run_worker()"
 ```
 
 ## Serialization
@@ -109,20 +179,20 @@ Arguments are serialized automatically:
 |------|--------|
 | JSON-serializable (str, int, list, dict) | JSON |
 | Pydantic models | `model_dump()` → JSON |
-| Custom objects, functions | dill (pickle) |
+| Custom objects, lambdas | dill (pickle) |
 
 ```python
+from typing import Callable
 from pydantic import BaseModel
 
 class User(BaseModel):
     id: int
     email: str
 
-def process(user: dict, transform: callable) -> None:
-    print(transform(user))
+def process(user: User, transform: Callable[[int], int]) -> None:
+    print(transform(user.id))
 
-# Pydantic model → dict, function → pickled
-pq.enqueue(process, User(id=1, email="a@b.com"), transform=lambda x: x["id"] * 2)
+pq.enqueue(process, User(id=1, email="a@b.com"), transform=lambda x: x * 2)
 ```
 
 ## Async Tasks
@@ -138,63 +208,22 @@ async def fetch(url: str) -> None:
 pq.enqueue(fetch, "https://example.com")
 ```
 
-## Worker
-
-```python
-# Run forever (poll every second when idle)
-pq.run_worker(poll_interval=1.0)
-
-# Process single task
-if pq.run_worker_once():
-    print("Processed a task")
-
-# Timeout (kill tasks running longer than 5 minutes)
-pq.run_worker(max_runtime=300)
-
-# Dedicated worker for specific priorities
-from pq import Priority
-pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})
-```
-
-## Dedicated Priority Workers
-
-Run separate workers for different priority tiers to ensure high-priority tasks aren't blocked:
-
-```bash
-# Terminal 1: High-priority worker (CRITICAL + HIGH only)
-python -c "from myapp import pq; from pq import Priority; pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})"
-
-# Terminal 2-3: General workers (all priorities)
-python -c "from myapp import pq; pq.run_worker()"
-```
-
-This ensures critical tasks get processed immediately even when the queue is busy.
+## Error Handling
 
-## Task Management
+Failed tasks are marked with status `FAILED`:
 
 ```python
-def my_task() -> None:
-    pass
-
-# Cancel a pending task
-task_id = pq.enqueue(my_task)
-pq.cancel(task_id)
-
-# Counts
-pq.pending_count()
-pq.periodic_count()
-
-# List failed/completed
-pq.list_failed(limit=10)
-pq.list_completed(limit=10)
+for task in pq.list_failed():
+    print(f"{task.name}: {task.error}")
 
-# Clear old tasks
+# Cleanup
 pq.clear_failed(before=datetime.now(UTC) - timedelta(days=7))
 pq.clear_completed(before=datetime.now(UTC) - timedelta(days=1))
-pq.clear_all()
 ```
 
-## Fork Isolation
+## Architecture
+
+### Fork Isolation
 
 Every task runs in a forked child process:
 
@@ -208,45 +237,20 @@ Worker (parent)
 ```
 
 The parent monitors via `os.wait4()` and detects:
+
 - **Timeout** - Task exceeded `max_runtime`
 - **OOM** - Killed by SIGKILL (OOM killer)
 - **Signals** - Killed by other signals
 
-## Multiple Workers
-
-Run multiple workers for parallel processing:
-
-```bash
-# Terminal 1
-python -c "from myapp import pq; pq.run_worker()"
-
-# Terminal 2
-python -c "from myapp import pq; pq.run_worker()"
-```
-
-Tasks are claimed with `FOR UPDATE SKIP LOCKED` - each task runs exactly once.
+### Concurrent Workers
 
-## Error Handling
-
-Failed tasks are marked with status `FAILED`:
-
-```python
-for task in pq.list_failed():
-    print(f"{task.name}: {task.error}")
-```
+Multiple workers can run in parallel. Tasks are claimed with `FOR UPDATE SKIP LOCKED`, ensuring each task runs exactly once.
 
 ## Development
 
-Start Postgres:
-
-```bash
-make dev
-```
-
-Run tests:
-
 ```bash
-uv run pytest
+make dev       # Start Postgres
+uv run pytest  # Run tests
 ```
 
 See [CLAUDE.md](CLAUDE.md) for full development instructions.

{python_pq-0.1.1 → python_pq-0.1.4}/README.md

@@ -2,14 +2,16 @@
 
 Postgres-backed job queue for Python with fork-based worker isolation.
 
+**[Documentation](https://ricwo.github.io/pq/)**
+
 ## Features
 
 - **Fork isolation** - Each task runs in a forked process. OOM or crashes don't affect the worker.
-- **Natural Python API** - Pass `*args, **kwargs` directly. Pydantic models and custom objects work.
+- **Natural Python API** - Pass functions directly with `*args, **kwargs`.
 - **Periodic tasks** - Schedule with intervals or cron expressions.
-- **Priority queues** - Five priority levels, higher priority tasks run first.
+- **Priority queues** - Five levels, higher priority tasks run first.
 - **Async support** - Async handlers work seamlessly.
-- **Concurrent workers** - Multiple workers with `FOR UPDATE SKIP LOCKED` prevents duplicate processing.
+- **Concurrent workers** - `FOR UPDATE SKIP LOCKED` prevents duplicate processing.
 
 ## Installation
 
@@ -17,7 +19,7 @@ Postgres-backed job queue for Python with fork-based worker isolation.
 uv add pq
 ```
 
-Requires PostgreSQL and Python 3.14+.
+Requires PostgreSQL and Python 3.13+.
 
 ## Quick Start
 
@@ -27,14 +29,16 @@ from pq import PQ
 pq = PQ("postgresql://localhost/mydb")
 pq.create_tables()
 
-def send_email(to: str, subject: str, body: str) -> None:
-    print(f"Sending email to {to}: {subject}")
+def send_email(to: str, subject: str) -> None:
+    print(f"Sending to {to}: {subject}")
 
-pq.enqueue(send_email, to="user@example.com", subject="Hello", body="...")
+pq.enqueue(send_email, to="user@example.com", subject="Hello")
 pq.run_worker()
 ```
 
-## Enqueueing Tasks
+## Tasks
+
+### Enqueueing
 
 ```python
 def greet(name: str) -> None:
@@ -42,45 +46,108 @@ def greet(name: str) -> None:
 
 pq.enqueue(greet, name="World")
 pq.enqueue(greet, "World")  # Positional args work too
+```
+
+### Delayed Execution
 
-# Delayed execution
+```python
 from datetime import datetime, timedelta, UTC
+
 pq.enqueue(greet, "World", run_at=datetime.now(UTC) + timedelta(hours=1))
+```
 
-# Priority
+### Priority
+
+```python
 from pq import Priority
-pq.enqueue(greet, "World", priority=Priority.CRITICAL)  # 100
-pq.enqueue(greet, "World", priority=Priority.HIGH)      # 75
-pq.enqueue(greet, "World", priority=Priority.NORMAL)    # 50 (default)
-pq.enqueue(greet, "World", priority=Priority.LOW)       # 25
-pq.enqueue(greet, "World", priority=Priority.BATCH)     # 0
+
+pq.enqueue(task, priority=Priority.CRITICAL)  # 100 - highest
+pq.enqueue(task, priority=Priority.HIGH)      # 75
+pq.enqueue(task, priority=Priority.NORMAL)    # 50 (default)
+pq.enqueue(task, priority=Priority.LOW)       # 25
+pq.enqueue(task, priority=Priority.BATCH)     # 0 - lowest
+```
+
+### Cancellation
+
+```python
+task_id = pq.enqueue(my_task)
+pq.cancel(task_id)  # Returns True if found and cancelled
 ```
 
 ## Periodic Tasks
 
+### Intervals
+
 ```python
 from datetime import timedelta
 
 def heartbeat() -> None:
     print("alive")
 
+pq.schedule(heartbeat, run_every=timedelta(minutes=5))
+```
+
+### Cron Expressions
+
+```python
 def weekly_report() -> None:
     print("generating report...")
 
-# Fixed interval
-pq.schedule(heartbeat, run_every=timedelta(minutes=5))
-
-# Cron expression (Monday 9am)
-pq.schedule(weekly_report, cron="0 9 * * 1")
+pq.schedule(weekly_report, cron="0 9 * * 1")  # Monday 9am
+```
 
-# With arguments
-def report(report_type: str) -> None:
-    print(f"generating {report_type} report...")
+### With Arguments
 
+```python
 pq.schedule(report, run_every=timedelta(hours=1), report_type="hourly")
+```
+
+### Unscheduling
+
+```python
+pq.unschedule(heartbeat)  # Returns True if found
+```
+
+## Workers
+
+### Running
+
+```python
+# Run forever, poll every second when idle
+pq.run_worker(poll_interval=1.0)
+
+# Process single task (for testing)
+processed = pq.run_worker_once()
+```
+
+### Timeout
+
+Kill tasks that run too long:
+
+```python
+pq.run_worker(max_runtime=300)  # 5 minute timeout
+```
+
+### Priority-Dedicated Workers
+
+Reserve workers for high-priority tasks:
+
+```python
+from pq import Priority
+
+# This worker only processes CRITICAL and HIGH
+pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})
+```
+
+Run multiple workers in separate terminals:
+
+```bash
+# Terminal 1: High-priority only
+python -c "from myapp import pq; from pq import Priority; pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})"
 
-# Remove schedule
-pq.unschedule(heartbeat)
+# Terminal 2-3: All priorities
+python -c "from myapp import pq; pq.run_worker()"
 ```
 
 ## Serialization
@@ -91,20 +158,20 @@ Arguments are serialized automatically:
 |------|--------|
 | JSON-serializable (str, int, list, dict) | JSON |
 | Pydantic models | `model_dump()` → JSON |
-| Custom objects, functions | dill (pickle) |
+| Custom objects, lambdas | dill (pickle) |
 
 ```python
+from typing import Callable
 from pydantic import BaseModel
 
 class User(BaseModel):
     id: int
     email: str
 
-def process(user: dict, transform: callable) -> None:
-    print(transform(user))
+def process(user: User, transform: Callable[[int], int]) -> None:
+    print(transform(user.id))
 
-# Pydantic model → dict, function → pickled
-pq.enqueue(process, User(id=1, email="a@b.com"), transform=lambda x: x["id"] * 2)
+pq.enqueue(process, User(id=1, email="a@b.com"), transform=lambda x: x * 2)
 ```
 
 ## Async Tasks
@@ -120,63 +187,22 @@ async def fetch(url: str) -> None:
 pq.enqueue(fetch, "https://example.com")
 ```
 
-## Worker
-
-```python
-# Run forever (poll every second when idle)
-pq.run_worker(poll_interval=1.0)
-
-# Process single task
-if pq.run_worker_once():
-    print("Processed a task")
-
-# Timeout (kill tasks running longer than 5 minutes)
-pq.run_worker(max_runtime=300)
-
-# Dedicated worker for specific priorities
-from pq import Priority
-pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})
-```
-
-## Dedicated Priority Workers
-
-Run separate workers for different priority tiers to ensure high-priority tasks aren't blocked:
-
-```bash
-# Terminal 1: High-priority worker (CRITICAL + HIGH only)
-python -c "from myapp import pq; from pq import Priority; pq.run_worker(priorities={Priority.CRITICAL, Priority.HIGH})"
-
-# Terminal 2-3: General workers (all priorities)
-python -c "from myapp import pq; pq.run_worker()"
-```
-
-This ensures critical tasks get processed immediately even when the queue is busy.
+## Error Handling
 
-## Task Management
+Failed tasks are marked with status `FAILED`:
 
 ```python
-def my_task() -> None:
-    pass
-
-# Cancel a pending task
-task_id = pq.enqueue(my_task)
-pq.cancel(task_id)
-
-# Counts
-pq.pending_count()
-pq.periodic_count()
-
-# List failed/completed
-pq.list_failed(limit=10)
-pq.list_completed(limit=10)
+for task in pq.list_failed():
+    print(f"{task.name}: {task.error}")
 
-# Clear old tasks
+# Cleanup
 pq.clear_failed(before=datetime.now(UTC) - timedelta(days=7))
 pq.clear_completed(before=datetime.now(UTC) - timedelta(days=1))
-pq.clear_all()
 ```
 
-## Fork Isolation
+## Architecture
+
+### Fork Isolation
 
 Every task runs in a forked child process:
 
@@ -190,45 +216,20 @@ Worker (parent)
 ```
 
 The parent monitors via `os.wait4()` and detects:
+
 - **Timeout** - Task exceeded `max_runtime`
 - **OOM** - Killed by SIGKILL (OOM killer)
 - **Signals** - Killed by other signals
 
-## Multiple Workers
-
-Run multiple workers for parallel processing:
-
-```bash
-# Terminal 1
-python -c "from myapp import pq; pq.run_worker()"
-
-# Terminal 2
-python -c "from myapp import pq; pq.run_worker()"
-```
-
-Tasks are claimed with `FOR UPDATE SKIP LOCKED` - each task runs exactly once.
+### Concurrent Workers
 
-## Error Handling
-
-Failed tasks are marked with status `FAILED`:
-
-```python
-for task in pq.list_failed():
-    print(f"{task.name}: {task.error}")
-```
+Multiple workers can run in parallel. Tasks are claimed with `FOR UPDATE SKIP LOCKED`, ensuring each task runs exactly once.
 
 ## Development
 
-Start Postgres:
-
-```bash
-make dev
-```
-
-Run tests:
-
 ```bash
-uv run pytest
+make dev       # Start Postgres
+uv run pytest  # Run tests
 ```
 
 See [CLAUDE.md](CLAUDE.md) for full development instructions.

{python_pq-0.1.1 → python_pq-0.1.4}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "python-pq"
-version = "0.1.1"
+version = "0.1.4"
 description = "Postgres-backed job queue for Python"
 readme = "README.md"
 authors = [
     { name = "ricwo", email = "r@cogram.com" }
 ]
-requires-python = ">=3.14"
+requires-python = ">=3.13,<3.15"
 dependencies = [
     "alembic>=1.17.2",
     "click>=8.3.1",
@@ -19,6 +19,12 @@ dependencies = [
     "sqlalchemy>=2.0.45",
 ]
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs-material>=9.6",
+    "mkdocstrings[python]>=0.29",
+]
+
 [project.scripts]
 pq = "pq.cli:main"
 

{python_pq-0.1.1 → python_pq-0.1.4}/src/pq/client.py

@@ -234,7 +234,10 @@ class PQ:
             Task object or None if not found.
         """
         with self.session() as session:
-            return session.get(Task, task_id)
+            task = session.get(Task, task_id)
+            if task:
+                session.expunge(task)
+            return task
 
     def list_failed(self, limit: int = 100) -> list[Task]:
         """List failed tasks.
@@ -252,7 +255,10 @@ class PQ:
                 .order_by(Task.completed_at.desc())
                 .limit(limit)
             )
-            return list(session.execute(stmt).scalars().all())
+            tasks = list(session.execute(stmt).scalars().all())
+            for task in tasks:
+                session.expunge(task)
+            return tasks
 
     def list_completed(self, limit: int = 100) -> list[Task]:
         """List completed tasks.
@@ -270,7 +276,10 @@ class PQ:
                 .order_by(Task.completed_at.desc())
                 .limit(limit)
             )
-            return list(session.execute(stmt).scalars().all())
+            tasks = list(session.execute(stmt).scalars().all())
+            for task in tasks:
+                session.expunge(task)
+            return tasks
 
     def clear_completed(self, before: datetime | None = None) -> int:
         """Clear completed tasks.

{python_pq-0.1.1 → python_pq-0.1.4}/src/pq/worker.py

@@ -13,7 +13,7 @@ import signal
 import sys
 import time
 import traceback
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
 from croniter import croniter
@@ -33,6 +33,12 @@ if TYPE_CHECKING:
 # Default max runtime: 30 minutes
 DEFAULT_MAX_RUNTIME: float = 30 * 60
 
+# Default retention: 7 days
+DEFAULT_RETENTION_DAYS: int = 7
+
+# Default cleanup interval: 1 hour
+DEFAULT_CLEANUP_INTERVAL: float = 3600
+
 # Exit codes for child process
 EXIT_SUCCESS = 0
 EXIT_FAILURE = 1
@@ -194,12 +200,45 @@ def _execute_in_fork(
                     raise Exception(f"Task failed with exit code {exit_code}")
 
 
+def _maybe_run_cleanup(
+    pq: PQ,
+    retention_days: int,
+    cleanup_interval: float,
+    last_cleanup: list[float],
+) -> None:
+    """Run cleanup if retention is enabled and interval has passed.
+
+    Args:
+        pq: PQ client instance.
+        retention_days: Days to keep completed/failed tasks. 0 to disable.
+        cleanup_interval: Seconds between cleanup runs.
+        last_cleanup: Mutable list containing last cleanup timestamp.
+    """
+    if retention_days <= 0:
+        return
+
+    now = time.time()
+    if now - last_cleanup[0] < cleanup_interval:
+        return
+
+    cutoff = datetime.now(UTC) - timedelta(days=retention_days)
+    completed = pq.clear_completed(before=cutoff)
+    failed = pq.clear_failed(before=cutoff)
+
+    if completed or failed:
+        logger.info(f"Cleanup: removed {completed} completed, {failed} failed tasks")
+
+    last_cleanup[0] = now
+
+
 def run_worker(
     pq: PQ,
     *,
     poll_interval: float = 1.0,
     max_runtime: float = DEFAULT_MAX_RUNTIME,
     priorities: Set[Priority] | None = None,
+    retention_days: int = DEFAULT_RETENTION_DAYS,
+    cleanup_interval: float = DEFAULT_CLEANUP_INTERVAL,
 ) -> None:
     """Run the worker loop indefinitely.
 
@@ -211,15 +250,22 @@ def run_worker(
         max_runtime: Maximum execution time per task in seconds. Default: 30 min.
         priorities: If set, only process tasks with these priority levels.
             Use this to dedicate workers to specific priority tiers.
+        retention_days: Days to keep completed/failed tasks. Default: 7.
+            Set to 0 to disable automatic cleanup.
+        cleanup_interval: Seconds between cleanup runs. Default: 3600 (1 hour).
     """
     if priorities:
         priority_names = ", ".join(p.name for p in sorted(priorities, reverse=True))
         logger.info(f"Starting PQ worker (priorities: {priority_names})...")
     else:
         logger.info("Starting PQ worker (fork isolation enabled)...")
+
+    last_cleanup: list[float] = [0.0]  # Mutable container for tracking
+
     try:
         while True:
             if not run_worker_once(pq, max_runtime=max_runtime, priorities=priorities):
+                _maybe_run_cleanup(pq, retention_days, cleanup_interval, last_cleanup)
                 time.sleep(poll_interval)
     except KeyboardInterrupt:
         logger.info("Worker stopped.")