vscode: handoff / pickup UI (right-click handoff, incoming pickup surface, read-only state on donor)

[amrmelsayed]

VSCode surface for the handoff / pickup mechanism proposed in #1008. Depends on #1008's CLI / state-machine landing first; this issue covers only the UI affordances that wrap the underlying commands. Filed separately because the design considerations are different (visual states, interaction flow, discoverability) and the work can ship as a follow-up once the CLI plumbing exists.

Context

#1008 proposes afx handoff <id> --to @user "note" (donor) and afx pickup <id> (recipient) for transferring an in-flight builder between team members, plus an exclusivity guard via the GitHub assignee and a currentArchitect field in status.yaml. Same plumbing serves both synchronous and asynchronous handoffs.

The CLI is the primitive. The VSCode extension currently has rich right-click affordances on builder rows (Open Builder Terminal, Open Worktree Folder, Run Worktree Setup, View Diff, Run / Stop Dev Server, Cleanup Builder). Handoff should fit naturally into that menu, and pickup should surface incoming handoffs in a way that doesn't require the recipient to be watching the GitHub notifications stream.

Three concrete surfaces

1. Donor side: right-click handoff

A new entry in the builder-row context menu (in the Builders tree, and adjacent surfaces where the row appears):

• Codev: Hand off to...

Clicking it:

• Opens a Quick Pick listing candidate recipients. Where the list comes from is the main open question (see decisions below).
• After the user picks a recipient, opens an InputBox prompting for an optional handoff note ("review the spec; my concern is X"). Empty is allowed.
• Validates the builder is at a stable boundary (per afx: handoff / pickup commands for transferring in-flight builders between team members #1008's policy) and surfaces a clear error if not, with the option to open the porch status pane to see where it's stuck.
• Runs afx handoff <id> --to @<recipient> "<note>" and shows a status-bar message on completion ("Handed off spir-42 to @bob").

2. Donor side: read-only state on the row

After handoff, the donor's local worktree is preserved as read-only (per #1008's leading option for that decision). The Builders tree row reflects this state visually:

• Distinct icon and/or muted color (specifics open).
• Row description includes (handed off to @bob) after the title.
• Context menu changes: most write actions (Open Terminal for spawn, Send Message, Cleanup) are hidden or disabled with tooltip "owned by @bob; use Take Back to resume control". Read actions (View Diff, Open Plan, Open Spec, Open Worktree Folder) remain available.
• A new entry appears: Codev: Take Back from @bob (a friendlier wrapper around afx pickup).

This treatment also covers the inbound case where Alice receives a builder she's never had before: it appears as a normal builder row once she runs the Take Back / Pick Up action, with no special UI from that point.

3. Recipient side: incoming-handoff surface

When a builder is handed to you (you become the GitHub assignee and currentArchitect is set to your name), the extension needs to surface that without forcing you to refresh manually. Two layered surfaces:

• Toast notification on detection: when the extension's overview poll observes a new builder assigned to you with currentArchitect == you and you have no local worktree, a notification fires: @alice handed off spir-42 to you. Note: "<note>". [Pick Up] [Open Issue] [Dismiss]. Pick Up runs afx pickup <id> and opens the resulting builder terminal. Toast surfaces both the sync case (immediate) and the async case (next time the recipient opens VSCode).
• Persistent tree entry: a section in the Builders view (or a new Incoming view) listing handoffs assigned to you that you haven't picked up yet. Each row shows #<id> from @donor: <note> with a Pick Up inline action. The tree entry persists across reloads until the handoff is picked up or reassigned away.

Once picked up, the row migrates into the normal Builders list and the incoming-section row goes away.

Open design questions

Initial leans below where I have them; all open for discussion.

1. Where does the recipient list come from?

The Quick Pick after Hand off to... needs candidate names. Sources, in order of "we already have this":

• (Lean) Architects discovered via Tower — afx status knows about architects in the local workspace and (via cross-workspace messaging) in other workspaces. Pre-populates with known-active names.
• GitHub collaborators on the repo — gh api repos/owner/repo/collaborators. Broader pool, but includes people who don't use Codev.
• A team file — codev/team.yaml or similar, hand-curated. Most reliable but requires maintenance.
• Free-text fallback — always present in the Quick Pick as "Other: enter a @username" so any user can be addressed.

The natural answer is probably Tower-known names first (top), then a free-text option. The GitHub-collaborators path adds latency and a credential dependency; defer unless it's clearly worth it.

2. Visual treatment for the read-only state

• Lean: muted icon color + (handed off to @bob) suffix in the description. Consistent with how VSCode treats inactive items elsewhere. No badge cluttering the row.
• Alternative: distinct badge icon (handshake glyph or similar) on the row. Higher signal, more visual noise.
• The icon vocabulary matters because the Builders tree already encodes phase / blocked / idle / active state via icons; we don't want to collide with those.

3. Where does the incoming-handoff tree section live?

• Option A: Inside the existing Builders view, as a sticky top group Incoming (2) above the area / phase groups. Discoverable, shares the view, no new container.
• Option B: A new top-level view Incoming in the Codev sidebar (sibling of Builders / Backlog / Pull Requests). More discoverable, takes sidebar real estate.
• Option C: Surface only via the toast notification; no persistent tree entry. Cleanest, but recipients miss handoffs that arrived while VSCode was closed.

Lean A. The Builders view is where you already look for "what builders need my attention"; a sticky group at the top fits the same mental model. Option C is too lossy.

4. Auto-acceptance vs explicit pickup

When a handoff arrives, should the extension auto-fetch the branch and create the worktree (so it's ready when you click in), or wait for explicit Pick Up?

• Lean explicit: nothing happens until the user clicks Pick Up. Predictable. No surprise disk writes. Auto-fetch can leak data the recipient hasn't agreed to engage with.
• Alternative auto-fetch: branches fetched in the background; the worktree only materializes on Pick Up. Trade-off: slightly faster pickup, slightly higher network / disk noise.

Lean explicit; an autoFetch: true config option could ship later if anyone wants it.

5. Note display surface

The handoff note ("review the spec; my concern is X") needs to land somewhere persistent that the recipient sees during the work, not just in the initial toast.

• Lean: prepend the note to the recipient's first interaction with the builder (e.g., a message printed in the spawned terminal banner, or surfaced in the Codev tab status header).
• Alternative: write it to the thread file as a [handoff from @alice]: entry. Durable, visible to future architects.
• The two aren't exclusive; thread-file is the more durable home, terminal-banner is the more immediate one.

What this isn't (for v1)

• Not a generalized team collaboration UI. The pattern here is strictly handoff: one architect owns at a time, transfer is a discrete event.
• Not concurrent editing visualization. There's no "Bob is typing..." surface because there's no concurrent editing.
• Not a permanent team view (existing Team panel work is separate scope).

Suggested protocol when ready to build

PIR, paired with or following #1008. The CLI is the load-bearing piece (the exclusivity guard, the state-machine transitions, the notification dispatch) and the VSCode surface is mostly UI wrapping. Plan-gate on this issue should pick the open decisions above and lock the visual vocabulary before code; dev-approval gate is useful here because the right-click menu / toast / tree treatment all need eyeballs on a running build before merging.

Related

• afx: handoff / pickup commands for transferring in-flight builders between team members #1008 (parent) — handoff / pickup CLI and state-machine work. Hard dependency; this issue is meaningless without it.
• Existing builder-row right-click menu in packages/vscode/src/views/builders.ts and friends — the natural integration point for Hand off to....
• Existing Codev Backlog and Builders tree groupings — the proposed incoming-handoff sticky-group lives in the same view container.
• afx send <workspace>:architect:<name> — the Tower-side messaging channel used for the sync notification leg; the toast detection logic can subscribe to it.