# Watch for (https://docs.vitrinka.ai/pm/watch-for)



## Watch for a change, not a reminder [#purpose]

A **Watch for** is a task that keeps looking for evidence: an upstream release, a merged pull request, a deployment or a new problem. It owns an approved observation plan and survives between checks without keeping a coding session alive. Its task type is `watch`.

Use a todo when you want a reminder to surface on a date or condition. Use a Watch for when you need repeated observations, evidence and a defined response to a finding. Following a task only subscribes you to that task's activity; it does not observe sources.

## From intent to an armed plan [#plan]

1. Create a task with type **Watch for** and open its Watch for section. A pending Intake draft must be accepted before it can watch anything.
2. Describe **What to watch for**, then choose **Draft plan with Eve**. Or choose **Write plan** to author it without AI.
3. Review the goal, sources, evidence needed for a match, lifetime, minimum/maximum interval, daily budgets, owner and follow-up. Eve's notes explain assumptions or sources the workspace could not offer.
4. Choose **Arm revision …** for the exact revision you reviewed. Saving or drafting a plan does not arm it.

Every saved plan edit creates a new, unarmed revision and stops checks under the old approval. Review and arm again. Adaptive timing inside approved bounds does not create a revision.

* **Once** (`once`) — stops after its finding and follow-up preparation are recorded. The Watch task can be done while the proposed implementation still waits in Intake or its follow-up is held.
* **Ongoing** (`ongoing`) — keeps watching for distinct findings. Unchanged evidence does not create another finding, even after re-arming a later revision.

An optional end time stops new checks after that time; it is not evidence that the goal was met. Revise the plan to keep watching.

## Choose sources the workspace can read [#sources]

A plan names at most eight sources. Availability is checked when saving and arming, and access is resolved again on each check.

| Source                                   | What it reads and needs                                                                                                                                                                                                                                                                                         |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vitrinka fact** (`vitrinka`)           | Project truth in the todo condition grammar: `pr <n> [merged\|closed]`, `release cut\|next`, `deployed <env> [<sha>]`, or `after <id>`. A facts-only plan is decided by the server, without Eve; all named facts must hold. Free-text conditions and session-local path/task conditions are not supported here. |
| **GitHub** (`github`)                    | Releases, tags, issues or pull requests from a named `owner/repo`, optionally filtered by title words. An admin connects the workspace's GitHub App with access to that repository; private repositories need the same installation access.                                                                     |
| **Hlídač problems** (`signals`)          | Open problem groups already recorded for a project routed by a configured Hlídač source, including Sentry/alert input. This is a read of Vitrinka's local problem record, not a new direct Sentry connector.                                                                                                    |
| **Public page or feed** (`page`, `feed`) | Text from a public page or RSS/Atom feed at an approved URL. No login, shell or browser session. Fetches are bounded and reject private-network destinations.                                                                                                                                                   |
| **Slack** (`slack`)                      | A selected channel, optionally a thread and matching words. An admin supplies a read-only Slack connection and explicit channel allowlist in workspace integrations; the app also needs access to the selected conversation. A plan cannot scan other channels or send messages.                                |

Removing a GitHub installation, disconnecting Slack or removing a channel takes effect on later reads. Fix the connection or select an available source; a saved plan is not a permanent access grant.

## Read the outcome and health [#outcomes]

Each check reports one of three outcomes:

* **Match** (`match`) — readable evidence supports a new finding, with source citations and observation times.
* **No match** (`no_match`) — the available evidence does not show a new match; previously handled findings are not new.
* **Unable to verify** (`unable`) — evidence is inaccessible, missing or inconclusive, or the check could not be interpreted. It is **never an all-clear**. A planned release date is not an actual release; an unreadable source is not proof that nothing changed.

The section shows last/next check, today's and total checks/tokens, findings and check history. Health explains what is happening and gives a recovery action:

| Health     | What to do                                                                                                                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idle`     | Write and arm a plan, or resume a deliberately paused watch. A cancelled watch stays stopped.                                                                                                   |
| `ok`       | Checks can proceed, or the one-shot found its evidence and prepared its follow-up. Read the accompanying diagnosis, not the badge alone.                                                        |
| `degraded` | One or two checks could not verify the goal. Read the diagnosis; retries back off automatically inside the plan's bounds.                                                                       |
| `failing`  | Three or more checks could not verify it. Repair the named source/permission/backend problem, then request a check.                                                                             |
| `blocked`  | Follow the specific fix: enable Eve, wait for the daily budget, revise an expired plan, reopen a closed task, or have an editor arm the revision after its approving member left the workspace. |

## Timing and budgets [#limits]

The plan's interval bounds must be between **15 minutes and one week**. Eve may suggest a next interval only inside those bounds; failures back off inside them too. Missed ticks coalesce to one current check, not a burst of historical calls.

* **Checks per day**: 1–96 per watch, counted on UTC days. Manual and unsuccessful checks consume a slot too.
* **Tokens per day**: optional, from 40,000 up to 2,000,000; `0` leaves the check count as the only plan budget. It is a hard ceiling: a check starts only while the most one check can spend (40,000 tokens) still fits under what is left of the day's budget.
* **Workspace cap**: `watch.checks.perDay` defaults to **500** across all watches. Accepted settings are 0–10,000; `0` removes this workspace cap, not the per-watch limits.

When a daily limit stops a check, the diagnosis names it and the next attempt moves to 00:05 UTC the following day. A check request cannot bypass budgets. Raising a plan budget is an edit that needs review and arming again.

## What a finding prepares [#findings]

The approved follow-up chooses what happens for each distinct finding:

* **Propose** (`propose`) — one evidence-linked draft enters [Intake](/pm/intake). A triager decides whether to accept, decline or merge it; the watch never auto-accepts new work.
* **Ready** (`ready`) — links an existing accepted task and records whether its own prerequisites allow work at preparation time. Open human/action gates, dependencies and other holds remain authoritative; a finding does not complete them. The findings list reads the follow-up's prerequisites again each time it is shown, so “ready” always means ready now.
* **None** (`none`) — records the finding without preparing a task.

The owner receives at most one notice per finding; an empty owner falls back to the task's assignee, then its reporter. Retries reuse the finding and its prepared draft rather than filing duplicates.

**A finding is not execution approval.** No watch launches a coding session, edits a repository, opens a pull request or deploys. Prepared work retains its normal implementation and release gates.

## Pause, resume, check or cancel [#controls]

* **Pause** holds an armed watch and fences in-flight results.
* **Resume** keeps the reviewed approval and waits out the plan's minimum interval since the last check. If the original approving member lost workspace membership, an editor must arm it again instead.
* **Check now** requests a check of an armed watch, subject to the **15-minute floor** since the last check and the same daily budgets. It is queued, not a promise of an immediate result.
* **Edit plan** stops the old approval; save, review and arm the new revision.
* **Cancel watch** stops it permanently. Create a new watch rather than resuming a cancelled one. A settled one-shot can instead be revised and re-armed to watch a new goal.

## Enterprise and AI switches [#switches]

| Switch                       | Effect on Watch for                                                                                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AIR_GAP`                    | Blocks public page/feed, GitHub and Slack observations. Local Vitrinka facts and already-recorded Hlídač problems remain readable. Eve requires an available in-perimeter backend.                               |
| Workspace `watchOutboundOff` | Disables those external watch sources without disabling local observations. It does not itself disable AI; use the AI controls separately.                                                                       |
| Automation `watch-check`     | Enables/disables automatic Eve interpretation; on by default. Does not block requested plan drafting or facts-only evaluation.                                                                                   |
| Workspace AI off (`aiOff`)   | Blocks Eve plan drafting and interpretation. Hand-written plans and facts-only checks still work. Non-fact plans report unable to verify rather than no match; source reads can still happen before the AI gate. |

Hlídač observations still need Eve to interpret them; being local does not make them facts-only. Disabling Eve does not silently cancel the watch or stop claimed checks from counting toward its budget.

## Agent and terminal doors [#agents]

Create with `create {kind: "task", type: "watch", …}`. MCP `update_watch` takes `op: "intent" | "draft" | "plan" | "arm" | "pause" | "resume" | "cancel" | "check"`. `plan` carries the whole plan; `arm` must name the reviewed `revision`.

Read `get_task {id, view: "watch"}` for the plan, health, usage and permitted actions; `view: "watch-history"` reads checks and findings.

The terminal uses `vitrinka task watch <id> [verb]`: omitted verb means `show`; the others are `history`, `intent`, `draft`, `plan`, `arm`, `pause`, `resume`, `cancel` and `check`. Use its help for flags and JSON output.

```bash
vitrinka task watch 42 show
vitrinka task watch 42 draft --intent "Tell me when the upstream fix is released"
# Read the returned plan before approving its revision.
vitrinka task watch 42 arm --revision 1
vitrinka task watch 42 history
```