source

Markdown input

Frontmatter for metadata, GFM for prose, the :::name{`{prop=value}`} block syntax for invoking Tux components, and fenced code blocks with language ids for syntax highlighting.

how-watcher-works.mdmd

---
title: How the agent watcher works
date: 2026-04-22
author: R. Chen
---

# How the agent watcher works

Landscape's file watcher is the long-running process on each agent host
that detects file events (create / modify / delete / move) and ships
them to the central index.

::tux-alert{variant="compliance" title="ITAR-tagged paths"}
This watcher must run with a tier-3 token when watching corpora that
contain ITAR-marked records. The default agent token is tier-1 and
will refuse the scope.
::

## Event types

The watcher emits four event types upstream:

| Type | Triggers when… |
|---|---|
| `create` | A new inode appears in a watched root |
| `modify` | An existing inode's content or mtime changes |
| `delete` | An inode disappears (soft-delete with 30d retention) |
| `move`  | An inode's path changes — single event, never delete+create |

::tux-callout{kind="stat"}
Move detection uses inode tracking on POSIX and SHA-256 correlation
on Windows. Either way, a single `move` event is emitted upstream
rather than a delete+create pair.
::

## Implementation note

```ts
// Coalesce events over a 250ms window to avoid shipping every
// keystroke during text-editor saves.
const debounced = debounce(events, { window: 250 });
```

Run it locally:

```bash
$ landscape agent watch /research/grants --root=local
[12:14:08] watcher: 4 paths registered
[12:14:09] heartbeat: ok (latency 38ms)
```

::tux-alert{variant="tip" title="Heartbeat cadence"}
The default heartbeat is every 60 seconds. Override with
`--heartbeat=30s` for tighter monitoring during a deploy or rolling
restart.
::

## Math

Inline equations flow with surrounding prose — the watcher's
detection-latency budget is bounded by $T_{poll} + T_{fs}$, where
$T_{poll}$ is the kernel poll interval and $T_{fs}$ is the filesystem
event-emission delay.

Display equations get their own block:

$$
T_{detect} = \max(T_{poll}, T_{fs}) + \frac{1}{N}\sum_{i=1}^{N} T_{network,i}
$$

Math renders via `remark-math` + `rehype-katex` in the MDC
pipeline; KaTeX CSS is imported globally in `globals.css`.

rendered

MDC output

The same source rendered live. Notice the tux-alert and tux-callout blocks render as the actual Vue components — same TTI rhythm as everything else in the style guide.

How the agent watcher works

Landscape's file watcher is the long-running process on each agent host that detects file events (create / modify / delete / move) and ships them to the central index.

ITAR-tagged paths

Event types

The watcher emits four event types upstream:

Type	Triggers when…
`create`	A new inode appears in a watched root
`modify`	An existing inode's content or mtime changes
`delete`	An inode disappears (soft-delete with 30d retention)
`move`	An inode's path changes — single event, never delete+create

Inline equations flow with surrounding prose — the watcher's detection-latency budget is bounded by $T_{poll} + T_{fs}$ , where $T_{poll}$ is the kernel poll interval and $T_{fs}$ is the filesystem event-emission delay.

Display equations get their own block:

T_{detect} = \max(T_{poll}, T_{fs}) + \frac{1}{N}\sum_{i=1}^{N} T_{network,i}

Math renders via remark-math + rehype-katex in the MDC pipeline; KaTeX CSS is imported globally in globals.css.

syntax

Block syntax for Tux components

MDC's block syntax invokes Vue components via :::name{`{prop=value}`}, with content between the opening fence and the matching close. Props are stringly-typed — wrap with : prefix for booleans and numbers (:dismissible="true"). Slots use #slot:

syntax-crib-sheet.mdmd

# Inline component (default slot)

::tux-alert{variant="warning" title="Be careful"}
Body content goes here.
::

# With a named slot

::tux-cta{tone="maroon" title="Ship it" dek="Two clicks."}
  ::tux-button{intent="primary"}
  Start scan
  ::
::

# Self-closing (no body)

::tux-section-header
Storage overview
::

# Inline span (one-line components)

A :badge[ITAR]{kind="tag"} flag here.

# Booleans + numbers — note the colon prefix

::tux-pagination{:total="412" :page-size="20" :show-status="true"}
::

where to use

Markdown vs Vue authoring

Use markdown (this) when content authors aren't writing Vue — tti-docs articles, blog posts, ADRs, changelog entries, marcom landing copy.
Use Vue templates when the surface needs interactivity beyond what MDC components expose, or when the page is structurally a layout (a dashboard, a session view, a directory) rather than long-form prose.
Mix freely — a Vue page can render an <MDC :value="..." /> block for the prose section and Vue components for the chrome. The Landscape docs site does this for product overviews.