Wake the supervisor promptly after catalog publication

[schickling-assistant]

Problem

Three successful axe agent new publications waited 21.0s, 18.4s, and 17.4s for a supervisor configured with a 30s audit interval. The issue attributed this to a timer-only loop, but the reported st2 revision already had a catalog declaration watcher. A pre-change 750-agent atomic-bundle test also received the expected declaration event, so the exact production event loss remains unproved.

Goal

Make cooperative catalog publication start a serialized reconciliation pass promptly, without removing prompt authorized direct Agent Spec replacement or weakening the timer fallback.

Decisions

• Add an independent, constant-cost watcher for atomic .st2/catalog-generation replacement. Every successful built-in catalog transaction already commits this file after durable publication.
• Keep the shallow declaration watcher for direct atomic KDL and bundle publication.
• Feed both unit wakes into the existing serialized loop. Keep the periodic audit as the correctness fallback.
• Revalidate the generation watch's control-directory identity after each pass, so directory replacement cannot leave a stale subscription.
• Reject a caller-side kick, socket, or signal. Those options add a second publication contract and still do not cover direct authors.

Verification

Before → after:

before  cooperative publications waited 17.4–21.0s for a 30s interval
before  exact-revision source inspection showed the declaration watcher already existed
after   generation commits have a separate one-directory backend subscription
after   a direct declaration launches on pass 2 with the fallback timer set to 60s

Run locally:

• nix develop --command cargo test --lib watch — 25 passed, including a 750-agent atomic bundle, generation replacement, control-directory replacement, fallback cadence, and negative event filters.
• nix develop --command cargo test --lib run::tests::supervisor_wakes_and_launches_a_new_direct_declaration -- --exact — passed.
• nix develop --command cargo test --lib run::tests::idle_supervisor_does_not_spin_on_its_own_catalog_reads -- --exact — passed.
• nix flake check --print-build-logs — passed after review hardening (22 x86_64-linux checks).
• axe vrs check --profile strict docs/vrs — no diagnostics for the new decision or experiment. The repository has unrelated pre-existing strict VRS diagnostics.

Pre-flip deviation: standalone cargo test --test invariants fails identically on pristine origin/main because an existing Resource Profile invariant references the removed test demand_observation_settlement_matrix_is_atomic_and_preserves_facts. All four new proof functions exist; the repository Nix gate passes.

Complexity

One small wrapper owns two notify backends and their independent retry state. No dependency or new process boundary is added.

Concerns

• The declaration watcher still scales with declaration-space directories. Resource payload and runtime trees remain excluded.
• The exact historical declaration-event loss was not reproduced. The generation channel removes that unknown from cooperative transaction latency rather than claiming a false root cause.
• A generation and declaration event can produce a no-op tail pass if the second event arrives after burst draining. Passes remain serialized.

Friction & bottlenecks

• The full Nix gate recompiles the Rust tree independently across many check derivations; this was captured in Agent Feedback.
• The Nix tracing hook repeatedly lacked write access to its shared trace log; this was recorded as a recurrence.

Follow-ups

• Run one post-deployment axe agent new canary to collect fleet evidence. The canary verifies deployment; it is not part of the source mechanism.
• Repair the pre-existing stale invariant proof reference separately.

References

• Closes up reconcile is timer-only: a published agent waits up to one full interval; new-agent default wait is shorter than the period #430
• docs/vrs/.decisions/0015-catalog-commits-and-direct-edits-use-independent-wake-channels.md
• docs/vrs/.experiments/2026-09-03-catalog-reconcile-wakeup.md

Posted on behalf of @schickling

field	value
agent_identity	dev3.direct.omp.4ndwdn2g
session	dev3.4ndwdn2g
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.1.2
agent_runtime	OMP 18.1.2
tooling_profile	dotfiles@7904863