# 1.8.9b9 — a Host that notices

This preview was published. Its Host-owned watch runtime was removed in
1.8.9b12 in favor of Agent-owned watches in the original
session ([#1788](https://github.com/openonion/connectonion/issues/1788)).

An opt-in preview on the 1.8.9 fix line (#1499). Stable remains 1.8.8.

## Watch an event

Declare a fixed file or timer source in `.co/host.yaml`:

```yaml
watch:
  - name: notes
    source: file
    path: notes.md
  - name: heartbeat
    source: timer
    every: 15m
```

The Host observes changes in the background and records events in
`.co/watch-state.sqlite3`. An idle watch starts a normal user turn in a stable
per-watch session. A later event arriving during that turn enters before the
next model decision through the copyable `watch_events` Agent plugin. If it
arrives during a final model call, the plugin requests one more iteration.
The internal `<system-reminder>` is a model-visible user-role message, not
provider system authority. Event data is labeled untrusted.

Push producers can call `connectonion.network.host.watch.emit_event()` with a
stable event ID. `co watch list` shows event status and failures;
`co watch retry <event-id>` requeues a failed event after its cause is fixed.
The queue reconciles a saved Agent answer with a lost acknowledgement after a
restart. Watch sessions proceed independently of one another.

The `watch_events` plugin can also be used in a plain Agent with
`plugins=[watch_events(claim_events)]`. Run `co copy watch_events` to edit its
source for your own Agent. The Host supplies observation, queueing, and idle
wakeup; the plugin owns only active-turn iteration delivery.

## Known limits

- Fixed-file polling runs every two seconds and can combine rapid writes.
  Missed timer intervals are coalesced into one event with a count.
- A turn accepts at most four batches of 16 live events; the rest remain
  queued for another turn. External tool effects are at least once after an
  uncertain crash, not exactly once.
- Agent-owned persistent watches that resume an arbitrary original session
  are separate work in [#1788](https://github.com/openonion/connectonion/issues/1788).

## Install

```sh
python -m pip install --upgrade 'connectonion==1.8.9b9'
co --version
```