feat(cms): auto-switch stale session branches to a fresh one on CMS open

[guitavano]

O que é

Quando alguém abre o CMS numa branch de sessão cujo último commit é mais antigo que a janela de staleness (2 dias), a sessão troca automaticamente para uma branch nova cortada da default branch. A branch velha não é apagada nem alterada — continua no GitHub, recuperável.

Motivação: alguém some por ~15 dias e volta pra uma branch defasada/quebrada; em vez disso passa a cair numa branch limpa e atual.

• Gated pela flag de org cms_auto_fresh_branch (default OFF) — nada muda até uma org ligar explicitamente.
• Uma troca por thread/aba (guarda por ref, mesmo padrão do branch-adopt que já existia).
• Dispara só em runtime === "cms".

Por que "data do último commit" e não "data de criação"

Git não guarda quando um ref nasceu e a API do GitHub não expõe isso de forma confiável. O sinal robusto — sem depender do nome da branch — é a data do commit para o qual o head aponta. Isso pega inclusive a branch nunca editada: o ref fica congelado no commit da main de quando nasceu, então uma branch de 15 dias tem head com data velha e é detectada como stale, mesmo sem nenhum commit próprio.

Mudanças

• api: getBranchHead no git-data client; decofile /status agora devolve lastCommitAt (null para a default branch e branches ainda não materializadas → nunca troca).
• web: predicado puro isBranchStale + query de status do decofile; efeito one-shot de troca no VmEventsBridge.
• shared: flag cms_auto_fresh_branch + contratos regenerados.
• e2e: stub do GitHub ganhou datas de commit + rota /branches/{branch}; novo teste de contrato do /status; asserts antigos do status atualizados para o campo novo.
• unit: isBranchStale.

Como ligar

ORGANIZATION_SETTINGS_UPDATE { flags: { cms_auto_fresh_branch: true } }

Testing

• ✅ tsc (api/web/shared/e2e), fmt, lint (0 erros), knip limpo
• ✅ unit isBranchStale (7/7)
• ⚠️ e2e escrito e type-checa; não rodado localmente (harness e2e exige Postgres em :5432) — roda no CI.

Caveat

Se a própria main ficar parada +2 dias, trocar uma branch limpa-porém-antiga geraria outra branch limpa (churn inofensivo, sem perda de dado) — irrelevante em repo ativo. Se incomodar, o passo seguinte é o servidor gravar branchCreatedAt no momento de criação do ref.

🤖 Generated with Claude Code

---

Summary by cubic

Auto-switches the CMS session to a fresh branch when the current branch's last commit is older than 2 days, so returning users don't keep working on a lagging branch. The stale branch stays intact on GitHub; the behavior is off by default behind the cms_auto_fresh_branch org flag.

Changes

• Adds getBranchHead to the git-data client and lastCommitAt to the decofile /status response (null for default/unmaterialized branches).
• Adds a pure isBranchStale check and a one-shot switch effect in VmEventsBridge, gated on runtime === "cms".
• Extends the GitHub e2e stub with commit dates and a /branches/{branch} route; adds a /status contract test and unit tests for isBranchStale.
• Orgs opt in via ORGANIZATION_SETTINGS_UPDATE with cms_auto_fresh_branch: true.

^{Written for commit 6d5c9d1. Summary will update on new commits.}