Skip to content

[ENHANCEMENT] Implement a singleton remote bridge orchestrator #1164

Description

@WebMad

Is your feature request related to a problem? Please describe.

The remote bridge architecture tracked in #650 must support multiple Zoo Code instances, such as separate VS Code windows, without starting an independent orchestrator for every instance. Concurrent extension activation can otherwise create duplicate orchestrator processes, socket conflicts, race conditions, and ambiguous command routing.

Describe the solution you'd like

Implement a standalone Remote Bridge orchestrator with at most one running process per user environment.

The orchestrator lifecycle should support:

  • a well-known local endpoint that Zoo Code instances can discover;
  • connect-first, start-second behavior when the experimental feature is enabled;
  • atomic file-based locking around orchestrator creation;
  • a second connection check after acquiring the lock and before launching the process;
  • stale-lock detection and safe recovery;
  • graceful shutdown and recovery after an orchestrator crash;
  • registration of multiple Zoo Code instances using unique instance IDs and workspace/window metadata;
  • heartbeat-based liveness monitoring and removal of stale registrations;
  • instance-scoped events and commands so messages are routed to the correct Zoo Code instance;
  • a platform-neutral lifecycle and protocol, with local IPC implementations appropriate to macOS, Linux, and Windows.

The orchestrator should be transport-agnostic. Terminal, mobile, Discord, and WebRTC integrations should connect through a provider interface rather than being embedded in the orchestrator lifecycle.

A simplified topology:

flowchart LR
    Z1[Zoo instance A] <-->|Local IPC| O[Singleton orchestrator]
    Z2[Zoo instance B] <-->|Local IPC| O
    Z3[Zoo instance C] <-->|Local IPC| O
    O <-->|Provider interface| P[Transport provider]
Loading

Describe alternatives you've considered

  • Starting one child bridge per Zoo Code instance. This is simpler initially but does not provide central orchestration and duplicates provider connections.
  • Using only a process ID or checking for an endpoint without a lock. Check-then-start behavior is vulnerable to races when multiple VS Code windows activate concurrently.
  • Holding a lock for every connection attempt. The lock is needed only to coordinate orchestrator creation; ordinary connections should not be serialized.
  • Using a fixed per-Zoo IPC server path. This can collide across multiple VS Code extension hosts and makes instance discovery and routing harder.

Additional context

Parent architecture and decision history: #650

Related feature-toggle issue: #1163

This issue covers the standalone orchestrator foundation, singleton lifecycle, and Zoo instance registry. Provider-specific remote experiences should be tracked separately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions