> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Timeout & Watchdog - Integration

> Feature ID: FW-49 Status: ✅ Implemented (2026-03-19) Spec Reference: FW-49-execution-timeout-watchdog.md Last Updated: 2026-03-16

**Feature ID:** FW-49
**Status:** ✅ Implemented (2026-03-19)
**Spec Reference:** [FW-49-execution-timeout-watchdog.md](../../../specs/fw/archive/FW-49-execution-timeout-watchdog.md)
**Last Updated:** 2026-03-16

***

## Overview

FW-49 adds execution deadline enforcement for workflow runs using a pg\_cron-triggered watchdog (`workflow-timeout-watchdog`) that invokes the `workflow-timeout-checker` Edge Function. It integrates with FW execution data, FW-47 dead letter handling, FW-25 compensation, and PF-10 notifications.

***

## Integration Points (from Spec)

| Dependency                       | Type                       | Purpose                                                                        |
| -------------------------------- | -------------------------- | ------------------------------------------------------------------------------ |
| PF-01 (Organizations & Sites)    | Platform                   | Tenant scoping and organization-level timeout settings                         |
| PF-10 (Notifications)            | Platform Integration Layer | Send timeout warnings, timeout notices, and escalation notices                 |
| FW-46 (Durable Execution Worker) | FW internal dependency     | Provides execution deadline fields and step-level timeout handling context     |
| FW-47 (Dead Letter Queue)        | FW internal dependency     | Store timed-out executions and timeout classification for post-mortem analysis |
| FW-25 (Error Recovery)           | FW internal dependency     | Trigger compensation actions for `fail`/`escalate` timeout behaviors           |
| FW-06 (Workflow Builder)         | FW internal dependency     | Configure timeout behavior per workflow definition                             |
| FW-22 (Execution Monitoring)     | FW internal dependency     | Surface at-risk and timed-out status/metrics in monitoring dashboards          |

***

## API / Edge Function Contracts

* **Watchdog edge function:** `supabase/functions/workflow-timeout-checker/index.ts`
  * Triggered by pg\_cron every 5 minutes.
  * Reads timeout settings from `fw_module_settings`.
  * Finds overdue executions (`deadline_at < now()`) and applies configured `on_timeout` action (`fail`, `cancel`, `escalate`).
  * Finds at-risk executions by warning threshold and emits one-time warning notifications.
* **Deadline extension edge function:** `supabase/functions/extend-execution-deadline/index.ts`
  * Requires authenticated user and admin authorization.
  * Extends `deadline_at`, resets warning sent flag, records audit event.

***

## Platform Integration Layer Usage

| Platform Layer      | Location                       | Usage                                                                       |
| ------------------- | ------------------------------ | --------------------------------------------------------------------------- |
| PF-10 Notifications | `@/platform/notifications`     | Sends timeout warning, timeout terminal-state, and escalation notifications |
| PF-01 Org context   | Platform foundation data model | Ensures all timeout processing and emitted records carry `organization_id`  |

***

## Security and Tenant Isolation

* Timeout checks operate with service role context for scheduled cross-tenant scanning; tenant identity is preserved in all writes/events.
* User-initiated deadline extensions require role and organization access checks before mutation.
* Notifications and DLQ entries include `organization_id` for downstream tenant-safe handling.
* Timeout error messages and extension reasons are sanitized and must not include PHI/PII.

***

## Event Contracts

FW-49 publishes planned workflow timeout events:

* `workflow.execution.timed_out`
  * Consumers: FW-47 (DLQ), FW-25 (compensation), monitoring/analytics listeners.
* `workflow.execution.deadline_extended`
  * Consumers: audit trail and monitoring listeners.

Event schemas are defined in the FW-49 spec and should be mirrored in the shared event contract documentation when implemented.

***

## Related Docs

* [FW-49 Spec](../../../specs/fw/archive/FW-49-execution-timeout-watchdog.md)
* [FW-46 Spec](../../../specs/fw/archive/FW-46-durable-execution-worker.md)
* [FW-47 Spec](../../../specs/fw/archive/FW-47-dead-letter-queue.md)
* [FW-25 Spec](../../../specs/fw/specs/FW-25-advanced-error-recovery-retry.md)
* [PF-10 Notifications](../../../specs/pf/specs/PF-10-notifications-system.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)