Upstream sync: Buzz Desktop 0.5.10 -> 0.5.11 — compare overlapping implementations and adapt to the stronger seam

[oscarlehuu]

Problem

Crew is pinned to Buzz Desktop desktop-v0.5.10 (1fb49103002e898607a7f6fd554cb51e94d92e08) in docs/crew/upstream-buzz.json. Buzz published Desktop desktop-v0.5.11 (248b9d1b7666aacbcb1485b76e81de30a271ba0e) on 2026-08-12. The relay manifest remains 0.2.1, but this release still carries substantial relay/database behavior, including migrations 0029 and 0030 and the new buzz-deletion crate.

The tag range contains 18 commits and changes 185 files (+23,495/-3,405). A measured git merge-tree --write-tree --messages origin/main desktop-v0.5.11 against Crew origin/main (850d0f49d) reports 19 conflict paths.

The conflict count understates the risk. Git auto-merges both idle-pool implementations into crates/buzz-acp/src/lib.rs:

• upstream feat(buzz-acp): idle re-sleep for woken lazy pools block/buzz#5682: idle_pool_sleep_reaper / idle_pool_sleep_due, BUZZ_ACP_IDLE_POOL_SLEEP, synchronous return to the existing Listening state;
• Crew Agent process lifecycle: idle engine spin-down with resume-first wake (durable session ledger) #169/feat(acp): idle engine spin-down with resume-first wake (#169) #179: Ready -> Draining -> Listening, BUZZ_ACP_POOL_IDLE_TIMEOUT, asynchronous drain/re-wake, durable exact-session ledger, and resume-first session/load.

A conflict-free auto-merge can therefore compile both timers and both teardown paths. That would be a semantic regression even if all textual conflicts were resolved.

The sync must not assume that existing Crew code wins. Where Buzz now provides the same seam, compare the two implementations and adapt to upstream when its structure, race handling, tests, or maintenance boundary are better. Retain Crew code only for a demonstrated Crew product contract that upstream does not satisfy.

Invariant: after the sync there is one idle clock, one sleep-eligibility decision, one teardown owner, and one wake path; an exact persisted session is resumed before any context rebuild.

Sync target

	Value
Crew source of truth	origin/main at implementation start
Current pin	desktop-v0.5.10 / 1fb49103002e898607a7f6fd554cb51e94d92e08
Target pin	desktop-v0.5.11 / 248b9d1b7666aacbcb1485b76e81de30a271ba0e
Product version	Desktop 0.5.10 -> 0.5.11
Relay manifest	0.2.1 -> 0.2.1 (schema/behavior still changes)
Measured range	18 commits; 185 files; +23,495/-3,405
Measured conflicts	19 paths on origin/main 850d0f49d
Real tag merge-base	f35930104bcbdb1332ff13735214ecb9fce1fc7b

desktop-v0.5.10 is not a direct ancestor of desktop-v0.5.11; its exclusive commit is release/sync metadata rather than a competing product-code line. Merge the exact desktop-v0.5.11 tag into a Crew sync branch. Do not merge upstream/main and do not open a PR against block/buzz (D-020).

What 0.5.11 brings

Directly relevant to Crew

• block/buzz#5682: woken lazy ACP pools re-sleep after an idle window.
• block/buzz#4950: standard Claude Code/Codex ACP prompt-response usage enters NIP-AM metrics.
• block/buzz#4552: channel about is delivered in the per-turn [Context] block with newline-spoof protection and a UTF-8-safe 500-character cap.
• block/buzz#5680: observer relay envelopes publish one batched store update rather than one update per event.
• block/buzz#5693: thread-activity persistence is coalesced instead of rewriting a large localStorage blob for every reply.
• block/buzz#5696: foreground recovery runs after the interaction/paint boundary instead of blocking the first focus turn.
• block/buzz#5662: live channel timelines no longer collapse to a single event when a pageless live window overlays populated cache.
• block/buzz#5574: channel settings and human/agent profiles are split into shared, smaller presentation components.

Additive product/operations work

• block/buzz#4425: durable operator-controlled whole-community deletion, buzz-admin deletions, buzz-deletion, migrations 0029/0030, write fences, resumable execution, and independent Postgres/S3/Redis verification.
• block/buzz#5684: atomic channel snapshot {channels, hash} for immediate sidebar paint plus revalidation.
• block/buzz#5475: buzz-agent output default 32768 -> 65536, recovery allowance 2 -> 3, and tool-first recovery guidance.
• block/buzz#5623: preserve the separator after persistent agent mentions.
• block/buzz#5627: route sent link-preview media through the authenticated proxy.
• block/buzz#5607: Databricks model discovery can perform bounded browser OAuth.
• block/buzz#4702: mobile threads settle on the latest authoritative reply.
• webbrowser 1.2.1 -> 1.2.4 addresses RUSTSEC-2026-0257.

Solution: compare, adapt, and delete duplication

The sync PR must include a short decision table for every semantic overlap. Each verdict must be one of:

1. Take upstream — upstream covers the full contract; remove the Crew implementation.
2. Compose on the upstream seam — use upstream as the owner and attach the smallest Crew-only behavior.
3. Retain a Crew contract — only when a named invariant/test proves upstream is insufficient; still reuse upstream helpers where possible.
4. Drop duplicate behavior — no two implementations, timers, stores, or lifecycle owners remain.

Do not score implementations by line count or by whether they are “ours.” Compare:

• product invariants and failure behavior;
• queue/enqueue/wake/respawn/cancel/outbox races;
• test discrimination and coverage;
• state ownership and number of lifecycle authorities;
• compatibility with Buzz models and extension seams;
• future upstream-sync cost;
• clarity of operator/user configuration.

Expected overlap verdicts to validate in Spike 0

Area	Upstream strength	Crew-only contract	Expected direction
Idle sleep	Pure idle_pool_sleep_due helper; complete gate matrix; authoritative respawn-in-flight signal; reaps completed JoinSet tasks	Draining state; work-during-drain re-wake; outbox/cancel-drain gates; durable ledger; exact session/load; stale-lineage refusal; Sleeping UI	Compose: upstream eligibility/race machinery feeds one Crew-capable drain/resume lifecycle; delete the second timer/path
ACP usage	Standard Claude/Codex prompt-response mapping with source-specific semantics	Hermes rotation provenance and honest compaction counters	Take upstream usage tracker; keep usage separate from compaction evidence; preserve Crew provenance fields
Channel description	Existing kind-39000 metadata seam; newline collapse; UTF-8-safe cap; DM exclusion	Crew role/routing/context composition	Take upstream formatter/parser and re-run prompt-composition contracts; do not create a Crew description model
Observer store	One publication per relay envelope; duplicate replay suppression	identity dedup, session_aging, control_result, Crew observer projections	Adapt Crew event variants into upstream batching pipeline; remove per-event duplicate publication logic
Foreground lifecycle	interaction -> paint -> trailing recovery boundary; coalesced resume	#164 workspace snapshot refresh and #174 observed-alive heartbeat	Use upstream scheduler; attach both Crew hooks without turning machine/app absence into observed idle time
Agent/profile UI	smaller shared panel/tabs/runtime components	Hermes profile actions, archive-on-delete, SOUL/model controls, Crew readiness	Take upstream component split; re-home Crew actions into the new seams rather than retaining old panels wholesale
Timeline	post-subscribe refresh and pageless-window correctness	#167 middle-page reconnect freeze fix	Take upstream and preserve #167; run the combined reconnect cases
Community deletion	New upstream-owned database/relay/admin model	Crew tables/events that may be community-scoped	Take upstream engine/migrations; audit Crew-owned tables for catalog/fence coverage rather than forking the deletion model

These are hypotheses, not permission to resolve mechanically. Spike 0 must confirm or change each verdict from actual merged source and tests.

Plan

Spike 0 — blocking implementation comparison

Before resolving the full merge:

1. Create a disposable trial merge of exact tag desktop-v0.5.11 onto the current origin/main.
2. Inventory both textual conflicts and semantically hot auto-merges. At minimum inspect:
   • crates/buzz-acp/src/{acp,config,lib,pool,pool_lifecycle,queue,relay,usage}.rs;
   • desktop/src-tauri/src/managed_agents/{runtime,reserved_env_keys}.rs;
   • desktop/src/features/agents/observerRelayStore.ts;
   • desktop/src/app/useAppShellLifecycleEffects.ts;
   • desktop/src/features/profile/ui/{UserProfilePanel,UserProfileAgentActions}.tsx.
3. Produce the overlap verdict table in the sync PR description before coding past the affected cluster.
4. Prove which idle predicate and state owner survive. A merged file containing both the upstream reaper and Crew idle transition is a failed spike result, not a starting implementation.
5. Check upstream tests against Crew tests. Preserve the stronger discriminating test even when its implementation is removed.

Slice 1 — merge and unify ACP lifecycle

1. Branch from fresh origin/main as sync/upstream-2026-08-13 and merge exact tag desktop-v0.5.11.
2. Reduce idle sleep to one config contract and one runtime policy. If backward compatibility needs both env names temporarily, they must alias one resolved value; they must not arm two timers.
3. Reuse upstream queue/wake/respawn race gates where they are stronger.
4. Preserve Crew's exact binding ledger, capability-gated session/load, post-load lineage validation, stale-lineage refusal, rebuild fallback, and Draining/re-wake semantics where the comparison proves they remain necessary.
5. Keep both ACP field sets that carry independent contracts: upstream standard usage plus Crew elicitation/rotation provenance. Do not choose one side wholesale.
6. Update docs/crew/UPSTREAM-SYNC.md to describe the resulting single idle-sleep seam; remove obsolete duplicate-key guidance.

Slice 2 — adopt upstream desktop seams

1. Fold Crew observer events/projections into upstream envelope batching.
2. Place feat(desktop): debounced exact local snapshot refresh on app focus #164 workspace refresh and Worktree storage reclaim: aggregate view, 48h/merged-PR idle policy, suggest-and-confirm bulk sweep (completes #59 P3) #174 alive heartbeat on upstream's foreground-ready scheduler while preserving observed-time semantics.
3. Re-home Hermes agent actions and archive-on-delete onto upstream's split profile components.
4. Preserve Evidence–CI cross-check badge: auto-compare test-run/diff-stat claims against the thread PR's real state #175's E2E bridge helper alongside upstream media-proxy helpers.
5. Apply D-022/D-033: extract Crew-owned growth from upstream-heavy files; never raise a line limit to make the sync pass.

Slice 3 — take correctness, storage, and deletion work

1. Take channel snapshot v2, thread-activity coalescing, timeline reconciliation, mention separator, preview proxy, agent recovery defaults, and Databricks OAuth behavior from upstream.
2. Take buzz-deletion and migrations 0029/0030 without creating a Crew deletion subsystem.
3. Audit every Crew-owned database table/write path for community scope and add it to upstream's live fence/catalog contract where required. Missing coverage must fail closed.
4. Test migrations against a database clone with existing Crew data and real Postgres/Redis/MinIO services.

Slice 4 — pins, workflows, docs, and evidence

1. Update docs/crew/upstream-buzz.json to 0.5.11 / desktop-v0.5.11 / 248b9d1b7666aacbcb1485b76e81de30a271ba0e.
2. Update the release contract test and Crew state/changelog where required.
3. Run gh workflow list --all; no newly imported out-of-scope workflow may be enabled.
4. Record any changed maintenance boundary in docs/crew/DECISIONS.md and update the UPSTREAM-SYNC.md touched-file table.
5. Include before/after evidence for profile/settings and reconnect timeline behavior.

Verify

ACP and lifecycle

• cargo test -p buzz-acp
• A source/contract test proves only one idle reaper/timer is active.
• One idle period invokes engine shutdown exactly once.
• Work arriving during drain is not stranded and causes one re-wake.
• In-flight turn, heartbeat, prompt task, retry-throttled queued work, wake/respawn, unflushed outbox, or cancel drain prevents teardown as appropriate.
• Completed respawn tasks are reaped and cannot permanently block future sleep.
• After sleep, an exact ledger match attempts session/load before rebuilding context.
• A stale/mismatched engine or workspace lineage refuses load and rebuilds fail closed.
• Standard Claude/Codex usage publishes without changing the honest Session compaction awareness: honest per-engine detection, aging threshold, guided handover to a fresh session #173 compaction count.
• Channel descriptions cannot inject a fake [Context] line and never appear in DM context.

Desktop

• Observer envelope batching preserves identity dedup, session_aging, control_result, transcript, and active-turn projections.
• Cmd-Tab/foreground recovery allows interaction/paint first, then refreshes the intended queries and relay state.
• Worktree storage reclaim: aggregate view, 48h/merged-PR idle policy, suggest-and-confirm bulk sweep (completes #59 P3) #174 observed idle does not advance while the app/machine was absent.
• Hermes profile model/SOUL/actions and archive-on-delete remain available through upstream's new panel structure.
• fix(desktop): keep interstitial older pages across reconnect freeze (#154) #167 reconnect/middle-page regression and upstream fix(desktop): preserve live channel timelines block/buzz#5662 one-live-event regression both pass.
• Channel snapshot falls back to a full fetch for v1, malformed, checksum-mismatched, relay-mismatched, or identity-mismatched data.
• Thread-activity pending writes flush on hide/pagehide/unmount/scope switch.

Relay/deletion

• Apply migrations 0029 and 0030 to a populated test database.
• Run affected relay/database/deletion/admin tests with Postgres, Redis, and MinIO.
• Crew-owned community-scoped tables are fenced or explicitly proven out of scope.
• Cross-community isolation and fail-closed catalog drift tests pass.

Gates

• just ci
• NuncioCrew Gate green.
• Manual NuncioCrew Upstream Sync run is green and its head SHA equals the sync branch HEAD.
• Desktop Smoke E2E and Desktop E2E Integration are run and reported honestly; D-032/D-047 keep them advisory, so a green Gate alone is not sufficient evidence.
• Mobile format/analyze/tests run for the inherited thread-detail change.
• git merge-base --is-ancestor desktop-v0.5.11 <sync-head> succeeds.

Definition of Done

• Exact tag desktop-v0.5.11 is merged through a reviewed PR into Nuncio-hq/crew.
• docs/crew/upstream-buzz.json pins 0.5.11, the exact tag, and commit 248b9d1b....
• The sync PR contains the measured overlap verdict table with evidence for every duplicated subsystem.
• There is exactly one idle policy/timer, one sleep decision, one teardown path, and one wake owner.
• No pair of Crew/upstream env keys can activate independent idle loops.
• Upstream's stronger race predicates/tests are retained or adapted; weaker duplicate Crew code is removed.
• Crew's exact-session resume, lineage validation, stale-lineage refusal, and rebuild fallback remain proven by tests.
• Upstream standard ACP usage and channel-description behavior are integrated without regressing Crew compaction/role routing.
• Upstream observer batching, foreground scheduling, profile component seams, storage fixes, and timeline fixes are adopted rather than copied into Crew parallels.
• Community deletion migrations and engine are integrated; Crew-owned community-scoped data is covered or explicitly proven out of scope.
• D-022/D-033 file-size rules pass without raising limits for Crew-owned growth.
• Required and advisory test outcomes are recorded with exact run URLs/SHA; failures are not hidden behind a green Gate.
• UPSTREAM-SYNC.md, Crew state/decision docs, and release contract tests describe the post-sync seams accurately.
• Thread Workbench: render a thread as the session it already is — one thread, two doors (dev workbench / business office) #186 is not implemented on the pre-sync observer/profile/timeline architecture.

Non-goals

• Implement Thread Workbench Thread Workbench: render a thread as the session it already is — one thread, two doors (dev workbench / business office) #186, workspace selector Workspace binding per thread: new worktree (default, pickable base branch) / main checkout / existing branch — composer selector for git Projects #187, or Cowork Cowork Projects: non-git folders with always-on shadow-git versioning (turn checkpoints, honest attribution, business-language restore) #188 in the sync PR.
• Redesign Crew's 30-minute product policy merely because upstream chose 15 minutes; policy changes need an explicit founder decision.
• Add a user-facing whole-community deletion button; upstream 0.5.11 ships an operator workflow.
• Invent a Crew-only usage schema, channel-description model, deletion engine, profile panel, or foreground scheduler beside upstream's implementation.
• Turn usage/context occupancy into a compaction signal.
• Make advisory Desktop E2E lanes required as a side effect of this sync.
• Merge upstream/main, push to block/buzz, or rewrite unrelated upstream code.