agent: scheduled verify and durability-refresh cadences

[mbertschler]

Summary

Closes the two standing automation-loop gaps from the friction log (F32, F33)
so a correctly configured household keeps its offsite evidence fresh with zero
typed commands — a prerequisite for the fingerprint-verified offload upgrade
that stacks on this (#155).

• F32 — scheduled verify. A verify_every cadence per content-addressed /
  packed destination, plus an [agent]-level default, drives the same pass
  as squirrel verify and records it as an audit run exactly like the manual
  command. Offsite bitrot detection no longer depends on anyone typing it.
• F33 — scheduled durability refresh. A pull_durability_every cadence per
  [nodes.X] gives relayed durability evidence its own clock, independent of
  sync activity. A receive-only node (the reference htpc) now refreshes its
  offload-gate evidence unattended, and any node keeps refreshing even when
  nothing changes — exactly when offload_max_evidence_age starts counting.

Both surface in the scheduler log with the existing kicked/finished/error
discipline and respect the marker/init boundary: verify is read-only, the
durability pull never rewinds a watermark (allowRewind is always false), and
neither ever bootstraps a destination — the agent does not escalate.

Changes

• config: verify_every on destinations (rejected on non-verifiable
  layouts) and on [agent] (fleet default); pull_durability_every on
  [nodes.X]. All reuse the existing cadence-floor parsing.
• agent/scheduler: two new non-volume evaluation phases keyed on
  destinations and peer nodes, with in-memory cadence watermarks. The start
  gate is broadened (anyScheduledWork) so a receive-only node with only a
  pull cadence still runs the scheduler. Verify/pull are injected as
  VerifyRunner / DurabilityPuller closures so the agent package keeps no
  import edge to sync.
• cmd/squirrel/agent: wires the closures over sync.VerifyRemote and
  sync.PullDurability; rclone is resolved for a verify-only schedule too.
• store: BeginDurabilityPullRun (shares a helper with
  BeginRemoteVerifyRun) records the pull as a volume-less audit run with a
  new pull-durability runs_audit transition — so it appears in squirrel runs yet stays out of the per-volume drift-audit reads.
• docs / design: reference-setup steady-state table + nas/htpc configs now
  exercise both cadences; configuration reference and agent guide document them.

No schema change — kind='audit' and free-text runs_audit transitions
already exist (issue #157 owns the v25 bump in parallel).

Design decision to double-check

Durability-pull runs are recorded with volume_id NULL (mirroring
BeginRemoteVerifyRun), which keeps them out of ListAuditRunsSince (the
drift-since-last-sync handshake) and the TUI's per-volume "last audit" — the
pulled volume/peer live in the runs_audit note instead. The cadence watermarks
are in-memory rather than persisted: both operations are cheap, idempotent, and
read-only w.r.t. content, so re-running once after an agent restart is harmless
and (for evidence freshness) desirable.

Testing

• go vet ./... — clean
• go test ./... — all packages pass
• gofmt -l — clean
• New tests: config parsing for all three knobs (incl. rejections); scheduler
  verify/durability cadence walks (due/skip/re-fire, no-op, error-consumes-
  cadence, stake filter, partial-on-rewind, nil-runner inert, broadened start
  gate); BeginDurabilityPullRun shape + handshake-isolation; CLI status
  mappers and wiring predicates.
• golangci-lint could not run locally (the sandbox's linter binary is built
  with go1.25 and refuses this module's go 1.26.1 directive); CI will run it.

Unblocks #155.

Closes #154

🤖 Generated with Claude Code

https://claude.ai/code/session_014Skm2Qm6wWUB7dD4CpPTz7

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds two new agent scheduler cadences to close automation gaps: periodic remote verification for content-addressed/packed destinations (verify_every) and periodic peer durability refresh (pull_durability_every) so evidence freshness doesn’t depend on manual commands or sync activity.

Changes:

• Config: add verify_every (per-destination and [agent] default) and pull_durability_every (per-node) with validation and tests.
• Agent/scheduler: add destination-scoped verify and (volume,peer)-scoped durability-pull evaluation phases, including deterministic logging and in-memory cadence watermarks.
• Store/docs/CLI wiring: record durability pulls as volume-less audit runs with a new pull-durability runs_audit transition; wire agent closures to sync.VerifyRemote and sync.PullDurability; document new knobs and update reference setup.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
store/runs.go	Factor out a shared helper for volume-less audit runs; add BeginDurabilityPullRun.
store/runs_audit.go	Add TransitionPullDurability audit transition constant.
store/remote_objects_test.go	Add test asserting durability-pull runs are volume-less and excluded from per-volume audit reads.
docs/src/content/docs/reference/configuration.md	Document verify_every (dest + agent default) and pull_durability_every (node).
docs/src/content/docs/guides/agent.md	Document scheduled verify and scheduled durability pull behavior.
design/reference-setup.md	Update reference household config/examples to exercise both new cadences.
config/nodes.go	Parse and expose pull_durability_every on nodes.
config/destinations.go	Parse/validate per-destination verify_every and reject it for non-verifiable layouts.
config/config.go	Add Destination.VerifyEvery to resolved config.
config/config_test.go	Add tests for destination verify cadence, agent default verify cadence, and node pull cadence parsing/errors.
config/agent.go	Parse and expose [agent] verify_every default cadence.
cmd/squirrel/agent.go	Wire scheduler closures for verify/durability-pull; broaden rclone setup to verify-only schedules; add run bookkeeping for durability pulls.
cmd/squirrel/agent_scheduler_test.go	Add unit tests for mapping/status helpers and wiring predicates.
agent/serve.go	Start scheduler loop when any scheduled work exists (volume, verify, or pull).
agent/scheduler.go	Add verify and durability-pull cadence evaluation phases with in-memory watermarks and deterministic ordering.
agent/scheduler_test.go	Update scheduler fixture to initialize new cadence fields/watermarks.
agent/scheduler_cadence_test.go	Add cadence-walk tests for verify and durability pulls (due/skip/refire/no-op/error/rewind/nil-runner/start-gate).
agent/agent.go	Extend agent config and public types for injected verify runner and durability puller.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.