feat(vigil): plugin-hook-liveness canary

[cirwel]

Why

On 2026-06-02 the unitares-governance-plugin hook chain was found dark for ~2.5 weeks. Every command in the plugin's hooks.json wrapped ${CLAUDE_PLUGIN_ROOT} in single quotes, which /bin/sh won't expand — so every hook resolved to a literal path and died "No such file". ~/.unitares/checkins.log had frozen at 2026-05-16 and nothing surfaced it. In a project whose thesis is observability of agent behavior, there was no canary asking "are my own hooks even firing?". (Plugin fix: cirwel/unitares-governance-plugin 0.4.5.)

This adds that canary.

Design

The load-bearing constraint: the canary is external to the hook chain. A heartbeat written by the hooks can't detect the hooks being un-dispatchable — the exact failure was that the wrapper never ran, so anything it was meant to touch never got touched. A self-reported signal is blind to its own death.

So PluginHookLiveness (running inside Vigil, a separate launchd process) compares two independent signals:

• Ground truth — ~/.claude/history.jsonl (advances on every prompt; the plugin can't suppress it).
• Hook artifact — newest mtime across checkins.log (send) + hook-skips.log (gated skip). Newest-wins means a healthy-but-gated chain still reads alive: the signal is "did a hook dispatch", not "did a check-in record".

It's a divergence test, not a staleness threshold: it fires only when there's recent CC activity and every hook artifact is stale — distinguishing "hooks dark" from "operator idle" so a quiet weekend doesn't page anyone.

Honest scope (no silent caps)

• The artifact set spans plugin and user-level (~/.claude/hooks) governance hooks → it answers "is the governance hook layer alive", slightly broader than "is the plugin chain alive". That's the right default.
• Soft spot: a single session held open >stale_hours with no dispatch could read dark. Default window (24h) makes this rare; severity is warning (advisory to verify), not critical.
• Needs a consumer. Per the EISV write-only-signal lesson, an alert nobody reads is the same failure one layer up. This emits a standard Vigil finding (fingerprint_key=plugin_hook_chain_dark) — route it to the Discord governance bridge / Sentinel where it'll actually be seen. (Follow-up, not in this PR.)

Config

VIGIL_HOOK_ACTIVITY_HOURS (default 12), VIGIL_HOOK_STALE_HOURS (default 24), VIGIL_CC_HISTORY_PATH, VIGIL_HOOK_ARTIFACT_PATHS.

Tests

9 unit tests on the pure assess() (no clock/fs coupling), including the 2026-06-02 reproduction (CC active + checkins.log 17 days stale → plugin_hook_chain_dark) and the newest-artifact-wins gated-chain case. Full Vigil suite: 100 passed.

Verified live: against this machine the check reads "live" off real turn_stop/auto_edit rows the now-fixed plugin hooks wrote this session (UUID cc447979) — checkins.log went from frozen-May-16 to actively writing.

Note

Pre-existing unrelated failure in test_lease_plane_canonicalize.py::...on_macos (sandbox TMPDIR is /private/tmp not /private/var) — reproduces with this branch's changes stashed; not introduced here.

🤖 Generated with Claude Code

[github-actions]

✅ Documentation Validation Passed

Tool Count: 7 tools tools
Version: 2.13.0

All documentation is synchronized with the codebase.

[cirwel]

Correction to the "needs a consumer" caveat above — verified, it's already wired.

I flagged in the description that routing plugin_hook_chain_dark to a consumer was a follow-up. That's wrong; I traced it and the canary is routed by construction, because it uses the standard Vigil finding contract:

PluginHookLiveness (ok=False, fingerprint_key=plugin_hook_chain_dark)
→ agent.py transition-emit (agents/vigil/agent.py:820, edge-triggered on healthy→dark via was_healthy, so one page per transition — no spam)
→ post_finding(event_type="vigil_finding", severity="warning", …)
→ POST /api/findings (src/http_api.py:1849) — passes validation: type ends in _finding, warning ∈ _FINDING_SEVERITIES, all required fields supplied
→ event_detector.record_event → broadcaster_instance.broadcast_event
→ dashboard WS + Discord bridge WS (the existing event-visibility pipeline).

Same path resident_tag_hygiene (which also emits warning) already rides. So no additional wiring is needed — the 2.5-week-silent failure this canary targets would now surface as a Discord/dashboard event on the transition. No follow-up required.