Preserve sidebar organization across upgrades without overriding saved choices

[ymichael]

Human comments

What was wrong

#3742 changed the unset sidebar organization default from By project to Custom. Existing installations without a persisted choice therefore changed views after upgrading, removing project headings and appearing to lose projects. The legacy browser migration also discarded choices matching the default, and the write path skipped explicitly selecting that default. Inserting a regular By project preference during upgrade would additionally override choices still stored only in a browser.

What changed

• Add a separate installation-default table and migration. Installations with existing projects, threads, or UI preferences receive a By project fallback; new installations retain Custom. The migration leaves saved preferences and project/thread data unchanged.
• Resolve preferences as saved server choice, then legacy browser choice, then installation fallback. Fallbacks retain revision zero so browser migration can save a choice without overriding a newer server preference.
• Apply server-provided revision-zero values in the client, persist explicit/default-valued choices, and reject older reconciliation responses when the cache has a newer revision. Reset saves the installation fallback as an explicit choice.
• Update configuration docs, CLI guide, and skill reference. Existing CLI/SDK preference APIs expose the behavior; no host-daemon wire change.

This addresses the upgrade/default transition. It does not change project rendering in explicitly selected Custom mode or reconstruct preferences discarded by older versions.

How you verified

• 590 database tests passed, including 13 new migration cases covering fresh installs, existing projects/personal threads/preferences, saved organization modes, unchanged data, and repeated startup: pnpm exec turbo run test --filter=@bb/db.
• 43 focused app tests passed: pnpm exec turbo run test --filter=@bb/app -- src/lib/ui-preferences src/components/sidebar/ProjectList.modes.test.tsx src/components/sidebar/SidebarHeaderControls.test.tsx.
• 12 server preference tests passed: pnpm exec turbo run test --filter=@bb/server -- test/public/public-ui-preferences.test.ts.
• App/server/database typechecks passed: pnpm exec turbo run typecheck --filter=@bb/app --filter=@bb/server --filter=@bb/db.
• App lint completed with zero errors (191 warnings): pnpm exec turbo run lint --filter=@bb/app.
• Isolated live upgrade: server initially returned By project at revision zero; a browser with legacy Custom uploaded it at revision one and cleared local storage. A second browser with stale By machine retained the server's Custom choice and cleared its legacy entry. Full project-creation UI verification remains incomplete because that control did not open in the isolated app.

AGENT GENERATED