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

# Durable watches

> Persist source cursors, notification decisions, quiet hours, and uncertain sends with explicit host services.

`defineWatch`, `describeWatch`, and `DurableWatch` are exported by `@agentium/harness`. Definitions are pure JSON operations. Constructing a watch does not subscribe to anything; work begins with an explicit `activate()` call.

For complete package documentation, including configuration, lifecycle methods, defaults, and examples, see [@agentium/harness durable watches](/harness/watches) and the [watch API reference](/harness/api/watches).

## Supply host services

A watch needs a durable task store, source adapter, persistent scheduler, scoped notification connector, authorizer, and deterministic filter. The optional `gmailWatchSource` accepts an already authenticated Gmail client and explicit push verifier. It loads no credentials or Google SDK by itself.

Host authorization checks verified tenant/actor identity, source access, fixed channel/destination, policy revision, grants, and requested amounts. Grant references are not authority by themselves. This implementation uses deterministic filters and makes no model calls.

## Process changes

`trigger(raw)` authenticates the source hint, checks principal/scope, and reads from the persisted cursor. A push-supplied cursor cannot advance state. Stable semantic event IDs deduplicate admission; unchanged wakes send nothing.

Cursor advancement and pending digest decisions commit together under a fenced lease. `flush()` prepares at most one digest, reserves the local-day notification cap, and sends through `DurableActionLedger`. Quiet hours and cooldowns use the configured IANA timezone and persist across restarts.

The scheduler stores idempotent, tenant-scoped `poll`, `renew`, and `flush` jobs and routes them to the correct watch version. Failed job publication leaves desired times in persisted state; repeating activation repairs scheduling. The host must actually run these scheduled methods.

## Lifecycle

| Method | Behavior |
| - | - |
| `activate()` / `resume()` | Revalidate access, establish/renew the source, and persist schedules |
| `pause()` | Stop new admission and cancel schedules; retain pending/unknown work |
| `update(nextDefinition, nextServices?)` | Require a newer version and pause the old version before activating its replacement |
| `delete()` | Tombstone the version and stop its owned subscription; preserve audit and unresolved effects |
| `inspect()` | Return authorized persisted state |
| `reconcile(outboxId)` | Reconcile a prior send without dispatching a notification |

Unknown delivery blocks newer digests until the connector supplies durable evidence. Pause/delete never automatically resend pending work. Leases prevent stale commits but cannot retract an already-sent notification.

## Gmail and operational limits

The host must enforce exclusive mailbox/configuration ownership so different watch versions do not compete for Gmail's desired subscription. Expired history triggers a bounded full sync with historical notifications suppressed. Renewals and polling are explicit scheduler work.

Watch versions have bounded wakes, events, state, outbox entries, and notification counts. Rotate or archive versions through host policy before limits are exhausted. Changing timezone requires a new watch identity.

Local and Mongo crash fixtures do not activate a live Gmail account or notification destination. Validate the chosen push verifier, scheduler, revocation behavior, and notification connector before deployment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.