Merge the two hook-freshness flags into one

[EdbertChan]

Summary

A helper warns when this project's copy on your computer is out of date. One setting now turns it off, keeps it offline, or lets it check online first.

Having two settings for one helper made it hard to see which one wins.

Now one setting takes three words. The old second setting is ignored, and the warning says so.

Review Claim

One setting picks between off, offline, and check online first for the out-of-date warning.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The hook only gives advice and never goes online unless the flag says fetch.

Slice Rationale

Bottom of a two-PR stack; the root README row follows as its own review unit.

• CATSTACK_HOOK_FRESHNESS=off|local|fetch, default local. 0 still means off.
• fetch replaces CATSTACK_HOOK_FRESHNESS_FETCH=1. A leftover _FETCH and unknown values are named in the advisory, never dropped silently.
• The flag is still read from the process environment only.

Non-goals

• No change to what the advisory checks or how often it fires.
• Reading the flag from .env files is not added here.

Test Plan

Test Plan

• python3 -m unittest discover -s engine/hooks/hook-freshness/tests before the fix:

  Ran 25 tests in 0.103s
  FAILED (failures=3, errors=2)
  

  after the fix:

  Ran 25 tests in 0.121s
  OK
  

• python3 scripts/ci/check_hook_test_coverage.py engine/hooks/hook-freshness → OK (1 hook(s) checked)
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main → unit engine-runtime: 3 file(s), all gates ok

Revert Plan

Revert Plan

• Safe to revert? Yes, after reverting the README PR stacked on it.
• Revert command: git revert <sha>
• Post-revert steps: set CATSTACK_HOOK_FRESHNESS_FETCH=1 again if fetch was in use.
• Data migration? No

🤖 Generated with Claude Code

[EdbertChan]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	Merge the two hook-freshness flags into one	#747	👈
2	README: document the three CATSTACK_HOOK_FRESHNESS settings	#748

[mergify]

Queued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 04:12 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #747 on main (282a0f8) #750
• 🔄 Queue rule updated
• ✅ Merged — 2026-09-17 04:19 UTC · at 7e5483706c03b4feca09d81d2eef1b38a8bbba32 · squash

This pull request spent 6 minutes 52 seconds in the queue, including 6 minutes 18 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate

[EdbertChan]

@Mergifyio queue admin-bypass