fix(env): verify up-to-date fast path against source, not just the lock

[fentas]

Problem (validated report — the residual #174 couldn't reach)

A consumer hit b update --envs-only reporting "up to date"/"225 keep" while the tree stayed stale — the CSI feature absent from disk after the lock had advanced. Healed only via git archive | tar -x.

Root cause, reproduced in a failing test on v4.18.4: the fast path trusts the lock as ground truth. At an unchanged commit it compares disk vs the lock's recorded shas (#174). A lock whose commit pointer was advanced without its content (legacy corruption from an older version) satisfies that check — disk == lock, both stale vs the pinned commit — so b update skips forever and b verify (disk-vs-lock) is equally blind. Self-sealing: the run that broke it hides the breakage.

S3 state:  disk = old content, lock.sha = old sha, lock.commit = NEW commit
#174 view: disk == lock → "(up to date)"          ← never looks at source

Fix — the skip must prove the tree matches source (user-selected option B: UX over compute)

lockedStateInSync now verifies three layers; any mismatch falls through to a full re-sync (strategy + safety gated, lock re-recorded):

1. Managed set — current config's glob match against the tree at the pinned commit must equal the lock's file set. Changed files: globs now sync immediately (previously silently deferred until the next upstream commit; the old comment suggested --force, which never existed for envs).
2. Lock — disk bytes hash to the recorded sha (unchanged, fix(env): re-sync on hash drift at unchanged commit (auto-heal stale lock) #174).
3. Source — for plainly-synced files (replace, no select, no b.pin), the disk content's git blob OID must match the ls-tree OID at the pinned commit. Computed in-process (gitcache.BlobOID, sha1/sha256 by repo format) — one git ls-tree subprocess total, no per-file spawns; the pinned commit comes from the cache (fetched at most once per machine); on any failure the check degrades to layer 2 rather than failing the update.

Intentional-divergence guards (no re-sync churn, each covered by a test): client/merge strategies, select-filtered files, and files carrying b.pin annotations keep the lock hash as their contract.

Semantics change (deliberate, documented)

Under replace, an interactive "keep" is now one-shot — the next update re-detects the divergence and restores source (previously the keep was silently absorbed until the next upstream commit; same end state, later). Durable local divergence ⇒ strategy: client/merge, select, or b.pin. Docs updated; the stale "b update --force re-syncs" tip in env-sync.mdx is removed.

Heal UX for the reported state

Plain b update: layer 3 detects the stale files → full sync → clean replace (plan rows are non-destructive updates since disk matches the lock) → passes strict/prompt gates automatically → disk + lock re-recorded at the pinned commit. Fully automatic, one run.

Tests

Fail-without-fix (verified by stashing the env.go change): TestSyncEnv_HealsStaleLockAtBumpedCommit, TestSyncEnv_ConfigChangeResyncsAtUnchangedCommit, TestSyncEnv_ReplaceKeepIsOneShot. Guards: PinnedFileFastPathStaysSkippable, ClientStrategyFastPathUnaffected, SelectFileFastPathSkips. gitcache: HasCommit, BlobOID (validated against git hash-object), ls-tree OID parsing. Full go build/vet/gofmt/test ./... clean.

Pushed over HTTPS via the gh token (ssh-agent has no key this session).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR hardens b update --envs-only’s “(up to date)” fast path so it only skips when the working tree matches not just the lockfile but also (when verifiable) the actual source tree at the pinned commit, preventing self-sealing stale/poisoned lock states.

Changes:

• Add a 3-layer fast-path validation in env sync (managed-set vs current config, disk vs lock hashes, and disk vs source blob OIDs for plain replace files).
• Extend gitcache to expose cached-commit presence and surface ls-tree entry type/OID, plus add BlobOID for in-process blob hashing.
• Add regression/guard tests for stale-lock healing and intentional divergence cases; update env-sync docs to reflect new semantics.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/gitcache/gitcache.go	Adds HasCommit, enriches TreeEntry with type/OID, parses ls-tree output, and adds BlobOID to compare disk bytes to source blobs.
pkg/gitcache/gitcache_extra_test.go	Adds tests for HasCommit, BlobOID, and ListTreeWithModesDir OID/type surfacing.
pkg/env/env.go	Replaces the old “disk vs lock only” skip check with lockedStateInSync including managed-set + source-blob verification (best-effort).
pkg/env/sync_source_verify_test.go	Adds regressions/guards for stale-lock-at-bumped-commit healing, config-change resync at unchanged commit, keep semantics, and divergence exceptions.
docs/env-sync.mdx	Updates tips to remove the non-existent --force guidance and document self-healing + one-shot keep behavior.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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

[fentas]

Review loop complete — 2 rounds (Copilot + subagent) + verification pass. Round 1 (7627001): streaming lock-only hashes, shared pin gate, sha256-safe helper, honest fetch-retry comments, docs fallback. Round 2 (7750925): structural pin confirmation so a b.pin mention can't exempt a file from source verification. Final (88b1ae8): fail-fast ls-tree parsing, fallback-docs caveat. Fast path now verifies managed set + lock + source blob OIDs; stale-lock states self-heal on plain b update. 4 fail-without-fix regressions + 3 stability guards. CI green. Merging.