Gate trail injection on enablement cache

[dipree]

https://entire.io/gh/entireio/cli/trails/652

This draft pull request was opened by Entire after CI was requested for the linked trail. Feel free to edit the title or body — the link above is what keeps the trail and PR connected.

---

Note

Medium Risk
Changes when agents receive the entire trail model-context hint and how enablement is cached across account/API/repo switches; hook SessionStart may perform bounded API refresh but TurnStart stays local-only.

Overview
TurnStart no longer treats a bare false clone preference as a permanent “no injection” decision. Trail hint injection now requires a fresh, scope-matched local cache (repo/API base/auth identity + TTL); missing, stale, or mismatched entries stay unknown and leave ContextInjectionDecided unset so a later refresh can still inject.

The clone-local cache is expanded in preferences with timestamp and binding fields, validated via new LocalIdentityCacheKey (local-only, no keychain/network on the hook read path). SessionStart best-effort refreshes stale/unknown entries under a short timeout; entire enable, successful entire trail usage, and bounded probes keep the cache updated. api.Client.TrailsEnabled only treats 403/404/410 as definitive disabled—401/5xx and transport issues return errors so ambiguous probes do not overwrite the cache.

^{Reviewed by Cursor Bugbot for commit de20872. Configure here.}

[Copilot]

Pull request overview

This PR tightens when the CLI injects the one-time entire trail model-context hint by introducing a scope-aware, TTL-bound clone-local enablement cache (repo + API base + auth identity), and by opportunistically refreshing that cache off the prompt path (SessionStart and trail-command execution). This reduces incorrect “sticky” enable/disable decisions across repo/API/account switches while keeping TurnStart local-only.

Changes:

• Expand clone-local ClonePreferences to include trails enablement cache scope bindings and a refresh timestamp, and gate context injection on a fresh, scope-matched cache.
• Add best-effort refresh and update paths for the cache (SessionStart refresh, trail-command wrapper refresh/update, enablement probe semantics).
• Update documentation and add/extend unit tests for the new cache behavior and API probe status handling.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/architecture/agent-guide.md	Updates agent integration docs to reflect fresh/scope-bound cache gating and SessionStart refresh behavior for trail hint injection.
cmd/entire/cli/trail_watch_cmd.go	Routes watch through the new authenticated trail wrapper and marks trails enabled on successful target resolution.
cmd/entire/cli/trail_review_cmd.go	Switches review target auth flow to the new authenticated trail wrapper (for consistent cache refresh/update behavior).
cmd/entire/cli/trail_context_cache.go	Implements scope-aware/TTL-bound cache read/write, best-effort refresh, and the runAuthenticatedTrailAPI wrapper that updates the cache based on command outcome.
cmd/entire/cli/trail_cmd.go	Switches trail subcommands to use the authenticated trail wrapper; updates create to record enablement on success and probe on error.
cmd/entire/cli/trail_cmd_test.go	Extends tests to validate repo/API/auth scoping and staleness behavior for the local enablement cache.
cmd/entire/cli/setup.go	Writes the enablement cache using remote-derived scope so non-forge remotes and origin changes fail closed.
cmd/entire/cli/settings/settings.go	Adds new clone-local preference fields: checked-at timestamp and scope binding (repo key, API base, auth key).
cmd/entire/cli/lifecycle.go	Refreshes stale/unknown cache on SessionStart (bounded) and changes TurnStart injection to only mark “decided” when cache is known (enabled/disabled).
cmd/entire/cli/lifecycle_test.go	Adds tests ensuring unknown cache does not permanently set ContextInjectionDecided, and that fresh true does.
cmd/entire/cli/auth/contexts.go	Adds LocalIdentityCacheKey() to validate cache scope without keychain/network access.
cmd/entire/cli/auth/contexts_test.go	Adds unit tests covering LocalIdentityCacheKey() for both active-context and env-token cases.
cmd/entire/cli/api/trails.go	Tightens TrailsEnabled probe semantics: only 403/404/410 are definitive false; other non-2xx become errors.
cmd/entire/cli/api/trails_test.go	Updates tests to cover 410 as definitive false and treat 401/5xx as errors (non-definitive).