Multi-instance and multi-user workspace sharing

[khaliqgant]

Overview

Allow multiple Pear instances — across different machines and different users — to connect to the same project workspace, see the same agents, share terminals, and collaborate in real time.

Prerequisites:

• Cloud agents land in a separate relay workspace from local agents — can't communicate #125 — broker must support joining an existing relay workspace by key
• Remote host support — spawn and connect to a broker on any machine #126 — remote host support (multiple instances need a shared broker to connect to)

---

Background

Pear is currently a single-user, single-machine app. Project state lives in ~/.config/Pear/config/projects.json on each machine independently. The relay workspace is per-account, per-session. There is no mechanism for two Pear instances — even the same user on two machines — to share a project view.

The infrastructure to build on is already in place:

• Relay workspace is already a cloud resource. RelayWorkspaceManager already knows how to rejoin an existing workspace by ID (relay-workspace.ts:170-185). If two instances joined the same workspace, they'd share the same messaging backbone.
• RelayCast (@relaycast/mcp, .mcp.json) is already the shared comms layer between agents. It can carry presence and coordination messages between Pear instances too.
• Remote host (Remote host support — spawn and connect to a broker on any machine #126) gives both instances a shared broker to connect to — without it, each instance would have its own local broker and there's nothing to share.
• Broker events are project-scoped (projectId is the primary key throughout IPC) — the isolation model is already right.
• Relayfile already handles bidirectional file sync between local and cloud workspaces.

---

What Needs to Be Built

1. Shared project definitions

The biggest architectural change. Today project state (channels, integrations, roots, host assignment) lives in local projects.json. For sharing, it needs to move to relay-backed cloud storage so multiple machines can read and mutate the same definition.

Options:

• Store canonical project state in the relay workspace record (relay cloud)
• Local projects.json becomes a cache/override layer; authoritative state is fetched from relay on open
• On conflict, relay cloud wins (last-write-wins or CRDT depending on complexity needed)

2. Workspace invite / join flow

A way for User A to invite User B into a workspace:

• User A generates an invite token (relay workspace ID + scoped access token)
• User B pastes it into Pear → Pear joins that relay workspace and fetches the shared project definition
• Both instances now see the same project

The RelayWorkspaceManager rejoin path (relay-workspace.ts:170-185) is the technical foundation — it just needs a UI surface and token-based auth on top.

3. Multi-instance broker coordination

When two Pear instances connect to the same remote host broker (#126), they need lightweight coordination to avoid conflicts:

• Session ownership: who owns which agent's PTY input? (reader/writer model — all instances receive output, only the "owner" sends input)
• Spawn coordination: prevent both instances from simultaneously spawning the same agent
• Conflict-free operations: stopping/releasing agents should be safe from any instance

Proposed mechanism: a RelayCast channel per project where instances broadcast presence, claim ownership of agents, and coordinate lifecycle operations. This reuses existing infrastructure.

4. Presence and permissions UI

• Show which users/instances are currently connected to the workspace
• Per-user permission levels: owner (full control), editor (can spawn/stop agents, send input), viewer (read-only terminal, no input)
• Visual indicator on agents showing who "owns" the active session
• Notifications when another user takes an action (spawns agent, pushes changes)

5. PTY fan-out

When two instances are connected to the same broker, both should receive PTY output chunks. The broker already supports multiple clients — this likely works today once the workspace key issue (#125) is fixed. Needs explicit testing and deduplication hardening (existing AGENTS.md duplicate-event guidance applies).

---

Build Order

This feature should be built in stages, each independently shippable:

Stage 1: Read-only observer
  Second instance can join, see agents and terminal output, but cannot interact.
  Requires: #125, #126, shared project definitions, invite flow.
  ~3 weeks.

Stage 2: Full collaboration
  Both instances can spawn/stop agents, send input, manage integrations.
  Requires: Stage 1 + broker coordination + permissions.
  ~2–3 additional weeks.

Stage 3: Polish
  Presence UI, per-user permissions, notifications, conflict resolution edge cases.
  ~1 week.

---

What This Unlocks

• Pair programming between two developers in real time, both watching the same agent
• Team lead reviewing an agent run in progress without interrupting the developer
• Same user working from two machines without losing context
• Foundation for a web-based observer view (no Electron required to watch a session)

---

Files Involved

File	Change
src/main/store.ts	Abstract project storage behind a fetch/sync interface; add relay-backed persistence
src/main/relay-workspace.ts	Add invite token generation and join-by-token flow
src/main/broker.ts	Multi-instance coordination via RelayCast channel; PTY fan-out testing
src/shared/types/ipc.ts	New events: workspace.onPresenceUpdate, workspace.invite, workspace.join
src/renderer/src/stores/	Presence store, permission-aware action guards
src/renderer/src/components/	Presence avatars, permissions UI, invite dialog
relay repo	Relay workspace shared state primitives (if not already sufficient)

---

Estimated Effort

~5–6 weeks total (Stage 1: ~3 weeks, Stage 2: ~2–3 weeks, Stage 3: ~1 week).