Throttle failed schema freshness checks

[qwrobins]

Summary

Fixes #135

• Records a schema freshness attempt before profile/network introspection work, then updates the cache to lastAttemptStatus: "success" only after a live schema comparison succeeds.
• Keeps failed/aborted advisory freshness probes inside the same 24-hour throttle window, preventing every normal command from firing another heavy introspection after a timeout.
• Adds a regression test using a configured profile fixture with a default team, matching realistic agent usage.
• Documents the 24-hour throttle for both successful and failed attempts, regenerates embedded skill docs, and bumps version to 0.7.3.

Breaking changes

None.

Verification

• bun test tests/core/schema/freshness.test.ts
• bun run typecheck && bun run test && bun run build && bun run build:binary

Summary by CodeRabbit

• Bug Fixes

  • Schema freshness checks now cache failed or aborted attempts for 24 hours, matching successful checks and eliminating unnecessary repeated introspection when network timeouts occur.

• Documentation

  • Updated documentation to clarify that both successful and failed schema freshness checks are cached for 24 hours.

• Tests

  • Added test coverage for schema freshness check failure scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 27cae87b-f45a-4eaf-9043-246b19295e7b

📥 Commits

Reviewing files that changed from the base of the PR and between 5ca5f2a and 7b5b827.

⛔ Files ignored due to path filters (1)

• src/generated/embedded-skills.ts is excluded by !**/generated/**

📒 Files selected for processing (7)

• CHANGELOG.md
• docs/commands.md
• docs/schema-and-generated.md
• package.json
• skills/linearctl/SKILL.md
• src/core/schema/freshness.ts
• tests/core/schema/freshness.test.ts

---

📝 Walkthrough

Walkthrough

Schema freshness checks now cache both successful and failed introspection attempts for 24 hours. The cache is pessimistically written as "failed" before the check runs, then upgraded to "success" if drift detection completes. This prevents repeated expensive schema introspection queries when the network probe times out or aborts.

Changes

Schema Freshness Failure Caching

Layer / File(s)	Summary
Freshness cache type and failure tracking implementation src/core/schema/freshness.ts	FreshnessCache type adds optional lastAttemptStatus field constrained to "success" or "failed". Before introspection, cache is written with lastAttemptStatus: "failed"; only upgraded to "success" after drift computation completes.
Test coverage for failed freshness attempts tests/core/schema/freshness.test.ts	Test fixture populates work profile with defaultTeam. New test forces an AbortError on introspection fetch, verifies the failed attempt is cached and subsequent checks within 60 seconds are throttled.
Documentation and version updates docs/commands.md, docs/schema-and-generated.md, skills/linearctl/SKILL.md, package.json, CHANGELOG.md	Docs across user, command, and contract layers clarified that freshness checks cache both successful and failed attempts for 24 hours. Version bumped to 0.7.3 with changelog entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• qwrobins/linearctl#95: Introduced the initial automated schema freshness cache; this PR extends it to persist failure attempts and throttle retries after aborted introspection.

Suggested labels

codex

Poem

🐰 The freshness check now learns from loss,
Caching failures without cost,
No more introspection on repeat,
When networks fail, the 24h beat.
Smart caching makes the checks complete!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title "Throttle failed schema freshness checks" clearly and concisely describes the main change: implementing caching of failed freshness attempts to prevent repeated introspection.
Linked Issues check	✅ Passed	The PR directly addresses both problems from issue #135: it now writes the cache before attempting introspection (using lastAttemptStatus field) and respects the 24-hour throttle for both successful and failed attempts, preventing repeated wasted introspection.
Out of Scope Changes check	✅ Passed	All changes are directly related to throttling failed schema freshness checks: documentation updates, version bump, test additions, and cache mechanism modifications all support the core objective.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-135-schema-freshness-throttle

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}