The sentinel

The forge hunts its own faults (src/crew/sentinel.ts, #1131). It reads what the forge already holds and files what is wrong, with the evidence quoted.

When. On the autonomy clock: a hunt an hour, and one sooner (never within ten minutes of the last) when a signal is new — queued checks waiting while no run uses a slot. A capacity setting away from its default is no signal and no finding: it is a line on /settings/capacity (#3269).

What it reads.

FaultRead from
a slot held by a finished runrun: queued work older than 30 min, nothing running or every lease lapsed
a check never green; pushes that cannot landthe last 20 check / agent run summaries per repository
retry stops, guard parksthe decision ledger (decisionsSince)
a hand-installed triggersqlite_master against a scratch database migrated from the schema
the same ERROR line again and againthe error ring (kernel/log.ts)

What it files. One issue per finding, titled Sentinel: …, with the evidence, the pillar, and what to look for when fixed. sentinel_finding remembers the key and the issue: a finding still open is a comment on its issue, and only when its evidence changed; one whose issue was closed and returned is filed again. It files in FORGE_SENTINEL_REPO (default trevato/forge) as the sentinel agent, else the first admin.

How it is labelled (#8856). Each finding declares a kind, and is filed with its labels, so the bug clock (src/flow/bugs.ts) runs from the filing and nobody has to sort it:

KindLabelsClock
security (a hand-installed trigger; a personal page not sent to sign-in)bug, high4 h
broken-route (a public page, link or documented route that answers 404 or 5xx)bug, high4 h
defect (every other finding, and the performance watcher's slow routes)bug48 h
cosmetic (a link that lands on / and is not Home)polishnone

A label the repository lacks is made (src/hunt/label.ts, shared by the sentinel and src/perf/duty.ts); labels already on the issue stay, and an issue adopted after its record was lost is labelled again. A budget breach also gets P0 Trust. Every detector declares its kind, and the type check refuses one that does not (#8969): a sentinel Finding requires kind, and the route hunters (src/hunt/door.ts, links.ts, contract.ts) and the performance watcher name their detector in DETECTOR_KINDS (src/hunt/finding.ts), which found reads the kind from.

What it shows. To a site admin only: the board's forge strip and the terminal palette's Sentinel command (as a toast) show the count of open findings and the last hunt's time. A hunt is synchronous, so there is no "hunting" state to show.

A check that has never been green is filed only for the sentinel's own repository. In any other repository it stays on that repository's checks and the degraded list.

A capacity setting away from its default is not a finding: the sentinel files nothing for it (#3269). On /settings/capacity the row of each such setting carries one muted line, "changed from X N days ago by who", and its Put back button (in the row's own form, beside Save) restores the default through changeCapacity (same validation, record, event and reversal). The line stays until the value is back at the default; nothing else reminds anyone. The JSON API and MCP carry the same fact: a setting away from its default has a changed field (at, by) in the capacity listing (listCapacity).

The setting:<key> findings filed before that are all closed; none raises an ask, and the capacity page's Put back is the one answer. The sentinel_kept table they once used is unread; a migration drops it once the additive rule (test/schema-additive.test.ts) allows a drop.

What it never quotes. Evidence passes through scrub (redactSecrets and any 32-character unbroken token) before it is filed, since the repository may be public.

Not done. Ingress routes and other edge objects are not in this database, so the sentinel cannot see them. It does not open fix pulls: a finding with a mechanical fix says what it is, and a crew run takes the issue up. Direction at its cap and WARN lines are not read yet.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs