feat(blacksmith-cache): add BLACKSMITH_BYPASS_CHECKOUT control-plane kill switch

[taha-au]

Summary

Introduces a shouldUseBlacksmithCache() helper that honors a new BLACKSMITH_BYPASS_CHECKOUT env var (driven by the per-installation bypass_blacksmith_checkout flag in the control plane). When set to "true", the action skips every Blacksmith-specific code path (mirror cache setup, alternates, dissociate, post-step cache commit) and behaves identically to upstream actions/checkout — usable as an emergency rollback for any customer hitting a checkout regression.

git-source-provider.ts swaps its single isBlacksmithEnvironment() gate for the new helper. Because the post-step cleanup gates on state values that are only set inside that block, the post step automatically becomes a no-op when the kill switch fires — no other changes required.

isBlacksmithEnvironment() is left untouched so its name continues to match its meaning ("am I running on a Blacksmith VM?").

Companion PRs:

• Backend (flag origin): https://github.com/useblacksmith/web/pull/new/ts/bypass-blacksmith-checkout
• fanew agent (env producer): https://github.com/FastActions/fa/pull/new/ts/bypass-blacksmith-checkout

Tests

__test__/blacksmith-cache.test.ts adds 4 new cases covering the env × kill-switch matrix:

• in Blacksmith env, kill switch unset → uses cache
• not in Blacksmith env, kill switch set → does not use cache (kill switch is a no-op outside Blacksmith)
• in Blacksmith env, BLACKSMITH_BYPASS_CHECKOUT=true → does not use cache (kill switch fires)
• in Blacksmith env, kill switch set to anything other than "true" → uses cache (strict equality)

dist/index.js rebuilt; npm run lint and npm run format clean.

Made with Cursor

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

---

Note

Medium Risk
Introduces an env-driven kill switch that changes whether the Blacksmith git mirror cache path runs, which can materially affect checkout performance/behavior in production. Logic is small and well-tested, but it gates a critical checkout flow.

Overview
Adds shouldUseBlacksmithCache() to gate all Blacksmith-specific checkout behavior on both being in a Blacksmith VM and not having BLACKSMITH_BYPASS_CHECKOUT set to the literal string "true" (logging when bypassing).

Updates the checkout flow in git-source-provider.ts to use this helper instead of isBlacksmithEnvironment(), and extends unit tests to cover the environment × kill-switch matrix; dist/index.js is rebuilt accordingly.

^{Reviewed by Cursor Bugbot for commit 64334e0. Bugbot is set up for automated code reviews on this repo. Configure here.}