chore(upstream): hand off blocked sync through t3code@ba9c9ae81dce

[maarco]

⚠️ Read this first

This PR contains no source changes and must not be merged as-is. It carries a blocker writeup and a verified resume artifact, so the sync can continue without redoing work already done.

The scheduled sync has been failing since Aug 3 — issues #10, #11, #12, #13, #14, #15 are all the same blockage. main never advanced past the last successful merge (5192f777f), so every daily run re-plans the same growing delta from the same merge base. Eight days of drift accumulated: 140 upstream commits, 41 conflicted files, ~150 hunks.

field	value
upstream source	ba9c9ae81dce4e554b4dd52abfd28d0c01b5c651
last upstream sha in main	5192f777fe54c2a2a359f6c25ecf5fbde46d49b0
target base	d0c01668c0f87b10bf952f929c55c7a8ca818fdf
new upstream commits	140
conflicted files	41 (27 resolved, 14 need your call)

PR #9 (bot sync through e60821f0e0d8) is a strict subset of this delta and should be closed in favour of whatever lands from this work.

Why it's blocked

Upstream 0de95407 feat: sidebar v2 is now the default sidebar restructured the whole sidebar: old Sidebar.tsx → LegacySidebar.tsx, SidebarV2.tsx → Sidebar.tsx, and the sidebarV2Enabled opt-in flipped to a legacySidebarEnabled opt-out.

Marcode's Sidebar.tsx is the unified workspace tree — a documented product contract and a manifest hotspot. Git therefore aligns Marcode's ~8,000-line sidebar against upstream's newly-promoted v2. Sidebar.tsx alone has ~5,100 lines inside conflict regions, including one hunk of 921 Marcode lines vs 2 upstream lines and another of 39 vs 527.

The settings contract now cleanly merges to carry both legacySidebarEnabled (upstream, default false) and unifiedWorkspaceSidebar (Marcode, default true) — two overlapping "which sidebar do I get" axes — while Marcode's useSidebarV2Enabled hook is gone. Deciding what those mean together is a product decision. Taking either side wholesale is forbidden by AGENTS.md and the runbook, and the runbook requires driving the real UI at 390px/820px before trusting a resolution here, which a headless container cannot do. So it stops rather than guessing.

14 files need your decision — Sidebar.tsx (18 hunks), RightPanelTabs.tsx (12), ChatView.tsx (10), ProjectScriptsControl.tsx (9), ThreadTerminalDrawer.tsx (7), index.css (7), rightPanelStore.ts (6), ChatHeader.tsx (5), AppSidebarLayout.tsx (5), SidebarChrome.tsx (3), mobile-showcase-environment.ts (3), plus rightPanelStore.test.ts, useHandleNewThread.ts, SettingsPanels.tsx (1 each).

What's resolved and verified

48 files hand-resolved — the other 27 conflicted files plus 16 carrying silent fork-boundary breaks and the renumbered migrations.

• vp run --filter @t3tools/contracts typecheck — clean
• vp run --filter @t3tools/client-runtime typecheck — clean
• vp run --filter t3 typecheck — clean
• 5 focused server suites — 44 passed
• client-runtime pagination + project grouping — 18 passed

No UI verification was performed. The web package cannot typecheck while the 14 files above still hold markers.

Silent fork-boundary breaks found (merged clean, NO conflict)

The dangerous class — each would have shipped a quietly broken Marcode:

1. Theme boot reads the wrong key. Upstream's new inline boot script reads localStorage["t3code:theme"]; Marcode renamed it to "marcode:theme". Every load would flash the wrong theme.
2. New appearanceFonts.ts didn't mirror Marcode's fonts — it documents its stacks as mirroring index.css and shows the resolved family to users; upstream's are system fonts, Marcode's are Inter/JetBrains.
3. --share bundled-dev speedup inert — dev-runner sets T3CODE_BUNDLED_DEV, Marcode's vite config reads MARCODE_BUNDLED_DEV.
4. New DesktopEarlyElectronStartup.ts read T3CODE_HOME while every Marcode writer sets MARCODE_HOME.
5. New DesktopStatePaths.ts defaulted to ~/.t3 instead of ~/.marcode, feeding both the early-startup path and DesktopEnvironment.
6. t3 pair read T3CODE_HOME — the documented pairing-token recovery command.
7. New migrate-dev-db script imported the pre-rename resolveWorktreeT3Home (didn't compile) and defaulted its source db to ~/.t3/userdata/state.sqlite, which doesn't exist here.
8. Upstream's new boot-service test hardcoded t3code.service; Marcode's unit is marcode.service.
9. projector.ts hunks mis-aligned — upstream's new defaultThreadEnvMode/faviconPath were aligned against Marcode's different project.workspace-layout-applied handler, so either side alone would have silently dropped them from the project-updated path.

Migration renumbering (correctness-critical)

Marcode owns id 33 = ProjectWorkspaceLayout, so shared migrations sit one higher. Upstream's new 36–40 collided with Marcode's 36 and were shifted to 37–41 (files git mvd, registry + test label updated). Renumbering an applied id would re-run or skip it on existing installs.

Other decisions worth a look

• http.ts — took upstream's HttpMiddleware.compression() refactor, kept Marcode's marcode://app origins (Marcode really registers that scheme, so CORS must carry it).
• bootService.test.ts — upstream's headline fix this sync is KillMode=mixed + OOMPolicy=continue. Kept Marcode's identity test and added upstream's new OOM test. T3_BOOT_SERVICE_UNIT stays upstream-shaped.
• threadSnapshotHttp.ts/threads.ts — both sides changed the same signature (Marcode's three-state found|missing|unavailable result vs upstream's pagination window). Combined, adapted upstream's loadOlderTurns call site and test harness; upstream's 18 pagination tests pass.
• tooltip.tsx — upstream bumped z-50→z-70 so tooltips overlay popovers/menus, but Marcode routes z through the inline floating-surface-z scale where a class is inert. Preserved the intent by adding portalOverlayTooltip: 13150. This touches Marcode's floating-surface z contract.
• .env.example — took upstream's now-default production Connect config, renamed T3CODE_*→MARCODE_* to match consumers.
• FilePreviewPanel.tsx — modify/delete; Marcode's deletion stands (retired surface, no importers).
• pnpm-lock.yaml regenerated via pnpm install. No coupled vendored subtree sync was needed.

Resuming

resolved-files.tar.gz holds the final content of all 48 hand-resolved files. Unpacking it over a freshly reproduced merge takes the conflict count from 41 down to exactly the 14 above.

This was verified end-to-end in a scratch worktree — the resulting tree is byte-identical to the state the typechecks and 62 passing tests ran against. (An earlier resolutions.patch on this branch did not apply: a HEAD-relative diff cannot target the unmerged index a conflicted merge leaves behind. Testing the recipe caught it; it has been replaced.)

Full recipe and writeup: docs/operations/upstream-sync-handoffs/ba9c9ae81dce/README.md