fix: resolve merge conflicts with main and update v2 fallback tests

- Take main's version for task_runner.py and async_task_runner.py
  (includes transient error handling, 404/405 detection)
- Update test_v2_fallback.py: _v2_available -> _use_update_v2,
  501 -> 405, fix e2e test infinite loop (mock batch_poll to return
  empty on second call)

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: v1r3n

.github/workflows/harness-image.yml

@@ -0,0 +1,97 @@
+name: Harness Worker Image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "Dockerfile"
+      - "harness/**"
+      - "src/**"
+      - "pyproject.toml"
+      - "poetry.lock"
+      - ".github/workflows/harness-image.yml"
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      deploy:
+        description: "Dispatch downstream deploy after the image is built"
+        type: boolean
+        default: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Calculate branch tag
+        id: vars
+        shell: bash
+        run: |
+          BRANCH="${{ github.ref_name }}"
+          CLEANED_BRANCH_NAME=$(echo "$BRANCH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')
+          echo "cleaned-branch-name=$CLEANED_BRANCH_NAME" >> "$GITHUB_OUTPUT"
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/conductor-oss/python-sdk/harness-worker
+          tags: |
+            type=raw,value=${{ steps.vars.outputs.cleaned-branch-name }}-latest,enable=${{ github.event_name != 'release' }}
+            type=raw,value=${{ github.event.release.tag_name }},enable=${{ github.event_name == 'release' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: harness
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          # Registry-backed BuildKit cache. Unchanged layers are reused across
+          # runs so rebuilding the same commit (or one with only minor diffs)
+          # is near-instant. The `:buildcache` tag lives alongside the image
+          # but only stores layer blobs, not a runnable image.
+          cache-from: type=registry,ref=ghcr.io/conductor-oss/python-sdk/harness-worker:buildcache
+          cache-to: type=registry,ref=ghcr.io/conductor-oss/python-sdk/harness-worker:buildcache,mode=max
+
+  dispatch-deploy:
+    if: |
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_dispatch' && inputs.deploy)
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CI_UTIL_DISPATCH_TOKEN }}
+          repository: conductor-oss/oss-ci-util
+          event-type: sdk_release
+          client-payload: |-
+            {"tag": "${{ github.event.release.tag_name || 'latest' }}", "repo": "${{ github.repository }}"}

.github/workflows/pull_request.yml

@@ -10,7 +10,6 @@ jobs:
   unit-test:
     runs-on: ubuntu-latest
     env:
-      COVERAGE_FILE: coverage.xml
       COVERAGE_DIR: .coverage-reports
     steps:
       - name: Checkout code
@@ -67,31 +66,29 @@ jobs:
 
       - name: Generate coverage report
         id: coverage_report
-        continue-on-error: true
         run: |
           coverage combine ${{ env.COVERAGE_DIR }}/.coverage.*
           coverage report
-          coverage xml
+          coverage xml -o coverage.xml
 
       - name: Verify coverage file
         id: verify_coverage
         if: always()
-        continue-on-error: true
         run: |
-          if [ ! -s "${{ env.COVERAGE_FILE }}" ]; then
-            echo "Coverage file is empty or does not exist"
-            ls -la ${{ env.COVERAGE_FILE }} ${{ env.COVERAGE_DIR }}
+          if [ ! -s coverage.xml ]; then
+            echo "coverage.xml is empty or does not exist"
+            ls -la coverage.xml ${{ env.COVERAGE_DIR }} || true
             exit 1
           fi
-          echo "Coverage file exists and is not empty"
+          echo "coverage.xml exists and is not empty"
 
       - name: Upload coverage to Codecov
         if: always() && steps.verify_coverage.outcome == 'success'
         continue-on-error: true
         uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          file: ${{ env.COVERAGE_FILE }}
+          file: coverage.xml
 
       - name: Check test results
         if: steps.unit_tests.outcome == 'failure' || steps.bc_tests.outcome == 'failure' || steps.serdeser_tests.outcome == 'failure'

Dockerfile

@@ -41,6 +41,19 @@ ENV CONDUCTOR_AUTH_SECRET ${CONDUCTOR_AUTH_SECRET}
 ENV CONDUCTOR_SERVER_URL ${CONDUCTOR_SERVER_URL}
 RUN python3 ./tests/integration/main.py
 
+FROM python_test_base AS harness-build
+COPY /harness /package/harness
+
+FROM python:3.12-alpine AS harness
+RUN adduser -D -u 65532 nonroot
+WORKDIR /app
+COPY --from=harness-build /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=harness-build /package/src /app/src
+COPY --from=harness-build /package/harness /app/harness
+ENV PYTHONPATH=/app/src
+USER nonroot
+ENTRYPOINT ["python", "-u", "harness/main.py"]
+
 FROM python:3.12-alpine AS publish
 RUN apk add --no-cache tk curl
 WORKDIR /package

LEASE_EXTENSION.md

@@ -0,0 +1,134 @@
+# Lease Extension (Automatic Heartbeat)
+
+When a worker picks up a task, the Conductor server starts a `responseTimeoutSeconds` timer. If the worker doesn't send an update before the timer expires, the server marks the task as timed out and re-queues it for retry.
+
+For long-running tasks (agent tool calls, LLM inference, data processing, batch jobs), the worker is actively executing but the server thinks it's dead. **Lease extension** solves this by automatically sending heartbeats that reset the timeout timer.
+
+## How It Works
+
+When `lease_extend_enabled=True`:
+
+1. Worker picks up a task with `responseTimeoutSeconds > 0`
+2. SDK starts tracking the task for heartbeats
+3. At **80% of `responseTimeoutSeconds`**, SDK sends a heartbeat (`TaskResult.extend_lease=True`)
+4. Server resets the task's `updateTime` to now, giving a fresh `responseTimeoutSeconds` window
+5. Heartbeats continue until the task completes, fails, or the worker shuts down
+
+```
+Timeline (responseTimeoutSeconds=120s):
+  0s          96s         192s        288s
+  |-----------|-----------|-----------|--→ task completes
+  poll      heartbeat   heartbeat   heartbeat
+             (80%)       (80%)       (80%)
+```
+
+The heartbeat fires at 80% of `responseTimeoutSeconds` (matching the Java SDK). This gives a 20% safety margin — if a heartbeat is slightly delayed, the task still has time before the server times it out.
+
+## Quick Start
+
+```python
+from conductor.client.worker.worker_task import worker_task
+
+@worker_task(
+    task_definition_name='long_running_analysis',
+    lease_extend_enabled=True,  # Enable automatic heartbeat
+)
+def analyze_dataset(dataset_id: str) -> dict:
+    """This task takes 5 minutes but responseTimeoutSeconds is 60s.
+    Heartbeats keep it alive automatically."""
+    results = run_expensive_analysis(dataset_id)
+    return {'results': results}
+```
+
+That's it. The SDK handles heartbeats automatically in the background.
+
+## Enabling Lease Extension
+
+Lease extension is **disabled by default** (matching the Java SDK). Enable it per-worker or globally:
+
+### Per-Worker (Decorator)
+
+```python
+@worker_task(
+    task_definition_name='my_task',
+    lease_extend_enabled=True,
+)
+def my_task(data: str) -> dict:
+    ...
+```
+
+### Per-Worker (Class)
+
+```python
+from conductor.client.worker.worker import Worker
+
+worker = Worker(
+    task_definition_name='my_task',
+    execute_function=my_function,
+    lease_extend_enabled=True,
+)
+```
+
+### Per-Worker (Environment Variable)
+
+```shell
+export conductor_worker_my_task_lease_extend_enabled=true
+```
+
+### Global (All Workers)
+
+```shell
+export conductor_worker_all_lease_extend_enabled=true
+```
+
+### Precedence
+
+Environment variables override decorator/constructor arguments:
+
+1. Task-specific env var (`conductor_worker_<task>_lease_extend_enabled`)
+2. Global env var (`conductor_worker_all_lease_extend_enabled`)
+3. Worker constructor / decorator argument
+
+## When to Use
+
+**Enable lease extension when:**
+- Task execution time may exceed `responseTimeoutSeconds`
+- Tasks involve external calls with unpredictable latency (LLM APIs, data pipelines)
+- You want the worker to hold the task continuously (not yield and re-poll)
+
+**You don't need lease extension when:**
+- Tasks always complete within `responseTimeoutSeconds`
+- You're using `TaskInProgress` with `callbackAfterSeconds` (the task is yielded back to the queue)
+- `responseTimeoutSeconds` is 0 (no timeout configured)
+
+## Lease Extension vs TaskInProgress
+
+These are two different strategies for long-running tasks:
+
+| | Lease Extension | TaskInProgress |
+|---|---|---|
+| **How it works** | Worker holds the task, heartbeats keep it alive | Worker yields the task, re-polls later |
+| **Task state** | IN_PROGRESS the whole time | Returned to queue between polls |
+| **When to use** | Continuous execution (LLM calls, streaming) | Incremental processing (batch chunks, polling external status) |
+| **Enable with** | `lease_extend_enabled=True` | Return `TaskInProgress(callback_after_seconds=N)` |
+| **Worker memory** | Task stays in worker memory | Task is released, re-polled with fresh context |
+
+You can combine both — enable `lease_extend_enabled` for safety while also using `TaskInProgress` for incremental polling.
+
+## Important Constraints
+
+- **`responseTimeoutSeconds`** is the time between updates. This is what heartbeats reset.
+- **`timeoutSeconds`** is the overall SLA wall-clock ceiling. **Cannot be extended by heartbeat.** Once exceeded, the task is TIMED_OUT regardless of heartbeats.
+- Heartbeats only fire when `responseTimeoutSeconds > 0` and `lease_extend_enabled = True`.
+- If the heartbeat interval would be less than 1 second (i.e., `responseTimeoutSeconds < 1.25`), heartbeats are skipped.
+
+## Retry on Failure
+
+If a heartbeat API call fails, the SDK retries up to 3 times with backoff (`1s`, `1.5s`, `2s`). If all retries fail, the error is logged and the SDK tries again on the next poll loop iteration. If the network is truly partitioned, the server will eventually time out the task — this is correct behavior.
+
+## Example
+
+See [examples/lease_extension_example.py](examples/lease_extension_example.py) for a complete runnable example that:
+- Defines a long-running worker with `lease_extend_enabled=True`
+- Creates a workflow with a short `responseTimeoutSeconds`
+- Runs the workflow and proves the task completes despite sleeping longer than the timeout

README.md

@@ -19,6 +19,7 @@ If you find [Conductor](https://github.com/conductor-oss/conductor) useful, plea
   * [Workers: Sync and Async](#workers-sync-and-async)
   * [Workflows with HTTP Calls and Waits](#workflows-with-http-calls-and-waits)
   * [Long-Running Tasks with TaskContext](#long-running-tasks-with-taskcontext)
+  * [Lease Extension for Long-Running Tasks](#lease-extension-for-long-running-tasks)
   * [Monitoring with Metrics](#monitoring-with-metrics)
   * [Managing Workflow Executions](#managing-workflow-executions)
 * [AI & LLM Workflows](#ai--llm-workflows)
@@ -59,9 +60,13 @@ conductor server start
 ## Install the SDK
 
 ```shell
+python3 -m venv conductor-env
+source conductor-env/bin/activate  # Windows: conductor-env\Scripts\activate
 pip install conductor-python
 ```
 
+> **Already in a virtual environment?** Skip the `venv` step and run `pip install conductor-python` directly. On macOS, Windows, or in containers where system Python is not locked down, you can also install globally.
+
 ## 60-Second Quickstart
 
 **Step 1: Create a workflow**
@@ -101,7 +106,7 @@ Create a `quickstart.py` with the following:
 ```python
 from conductor.client.automator.task_handler import TaskHandler
 from conductor.client.configuration.configuration import Configuration
-from conductor.client.orkes_clients import OrkesClients
+from conductor.client.orkes_clients import OrkesClients  # works with OSS Conductor and Orkes Conductor
 from conductor.client.workflow.conductor_workflow import ConductorWorkflow
 from conductor.client.worker.worker_task import worker_task
 
@@ -127,6 +132,8 @@ def main():
     workflow.register(overwrite=True)
 
     # Start polling for tasks (one worker subprocess per worker function).
+    # Note: scan_for_annotated_workers=True only discovers @worker_task functions that have
+    # already been imported. If workers are in a separate module, import it first.
     with TaskHandler(configuration=config, scan_for_annotated_workers=True) as task_handler:
         task_handler.start_processes()
 
@@ -162,7 +169,7 @@ python quickstart.py
 > See [Configuration](#configuration) for details.
 
 That's it — you just defined a worker, built a workflow, and executed it. Open the Conductor UI (default:
-[http://localhost:8127](http://localhost:8127)) to see the execution.
+[http://localhost:8080](http://localhost:8080)) to see the execution.
 
 ---
 
@@ -271,6 +278,26 @@ def batch_job(batch_id: str) -> Union[dict, TaskInProgress]:
 
 See [examples/task_context_example.py](examples/task_context_example.py) for all patterns (polling, retry-aware logic, async context, input access).
 
+### Lease Extension for Long-Running Tasks
+
+For tasks that run longer than `responseTimeoutSeconds` (e.g., LLM inference, data pipelines, batch jobs), enable automatic lease extension. The SDK sends heartbeats at 80% of `responseTimeoutSeconds`, resetting the server's timeout timer so the task stays alive:
+
+```python
+from conductor.client.worker.worker_task import worker_task
+
+@worker_task(
+    task_definition_name='train_model',
+    lease_extend_enabled=True,  # Automatic heartbeat — keeps task alive
+)
+def train_model(dataset_id: str) -> dict:
+    """Runs for 10 minutes, but responseTimeoutSeconds is only 60s.
+    Heartbeats at 48s intervals keep the lease alive."""
+    model = train(dataset_id)
+    return {'model_id': model.id, 'accuracy': model.accuracy}
+```
+
+Disabled by default. Enable per-worker via decorator, constructor, or environment variable (`conductor_worker_<task>_lease_extend_enabled=true`). See [LEASE_EXTENSION.md](LEASE_EXTENSION.md) for the full guide.
+
 ### Monitoring with Metrics
 
 Enable Prometheus metrics with a single setting — the SDK exposes poll counts, execution times, error rates, and HTTP latency:
@@ -403,6 +430,7 @@ See the [Examples Guide](examples/README.md) for the full catalog. Key examples:
 | [kitchensink.py](examples/kitchensink.py) | All task types (HTTP, JS, JQ, Switch) | `python examples/kitchensink.py` |
 | [workflow_ops.py](examples/workflow_ops.py) | Pause, resume, terminate, retry, restart, rerun, signal | `python examples/workflow_ops.py` |
 | [task_context_example.py](examples/task_context_example.py) | Long-running tasks with TaskInProgress | `python examples/task_context_example.py` |
+| [lease_extension_example.py](examples/lease_extension_example.py) | Automatic heartbeat for long-running tasks | `python examples/lease_extension_example.py` |
 | [metrics_example.py](examples/metrics_example.py) | Prometheus metrics collection | `python examples/metrics_example.py` |
 | [fastapi_worker_service.py](examples/fastapi_worker_service.py) | FastAPI: expose a workflow as an API (+ workers) | `uvicorn examples.fastapi_worker_service:app --port 8081 --workers 1` |
 | [helloworld.py](examples/helloworld/helloworld.py) | Minimal hello world | `python examples/helloworld/helloworld.py` |
@@ -427,6 +455,7 @@ End-to-end examples covering all APIs for each domain:
 | [Worker Design](docs/design/WORKER_DESIGN.md) | Architecture: AsyncTaskRunner vs TaskRunner, discovery, lifecycle |
 | [Worker Guide](docs/WORKER.md) | All worker patterns (function, class, annotation, async) |
 | [Worker Configuration](WORKER_CONFIGURATION.md) | Hierarchical environment variable configuration |
+| [Lease Extension](LEASE_EXTENSION.md) | Automatic heartbeat for long-running tasks |
 | [Workflow Management](docs/WORKFLOW.md) | Start, pause, resume, terminate, retry, search |
 | [Workflow Testing](docs/WORKFLOW_TESTING.md) | Unit testing with mock outputs |
 | [Task Management](docs/TASK_MANAGEMENT.md) | Task operations |