Add pluggable workspace runtimes

[boudra]

Paseo does not need to become a sandbox, container manager, or remote-workspace platform. It needs one stable workspace-runtime boundary so those capabilities can be supplied by independent implementations.

This PR makes Local, Worktree, and registered external runtimes first-class implementations of the same workspace abstraction. Paseo owns the contract and workspace helper; runtime authors own materialization, isolation, process lifecycle, and implementation-specific configuration.

The architecture

Paseo workspace features
  agents · terminals · files · watches · Git · scripts · setup
                         │
                         ▼
              workspaceId-bound runtime API
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
        Local         Worktree      command runtime
                                      │
                             container / sandbox /
                              VM / remote machine

Paseo core knows that a runtime is registered and what generic capabilities it exposes. It does not know whether an external runtime uses Docker, a local sandbox, a VM, SSH, or a hosted service.

• Local and Worktree remain built-in, optimized implementations. They use the same workspace-ID-bound surface while retaining host-specific optimizations such as shared Git observation.
• External runtimes are standalone executables registered through daemon configuration. They implement the public CLI contract and may live in separate repositories and release independently.
• Runtime options are opaque. Paseo passes arbitrary JSON from trusted configuration to the runtime unchanged. Docker-specific mounts, images, networks, or sandbox policies never become Paseo schema.
• No fallback leaks. If a selected runtime fails, Paseo reports the failure; it does not silently execute the command on the host.

What crosses the boundary

Paseo routes workspace-scoped behavior through the selected runtime:

• provider discovery and agent processes;
• terminals and PTYs;
• file operations and recursive watches;
• Git and forge commands;
• scripts, setup, and archive commands;
• workspace materialization, pause, resume, destruction, and reconciliation.

The runtime owns physical placement. Paseo addresses the workspace by workspaceId; cwd in public placement is descriptive compatibility data, not execution authority.

Workspace setup remains asynchronous. A runtime only blocks creation until usable workspace content exists. Paseo then publishes the workspace, starts the existing Setup lifecycle, streams its steps and output, and allows the initial agent to run while setup continues.

Runtime authoring reference

Runtime authors depend on two small Paseo packages:

• @getpaseo/workspace-runtime-contract — strict versioned schemas and TypeScript types for the runtime CLI.
• @getpaseo/workspace-helper — the official root-confined executable for structured files and watching. Runtimes place it on the workload PATH; they do not reimplement its protocol.

The configured executable receives one operation:

describe
create --workspace-id <id>
inspect --workspace-id <id>
exec --workspace-id <id>
signal --workspace-id <id> --exec-id <id> --signal <signal>
pause --workspace-id <id>
resume --workspace-id <id>
destroy --workspace-id <id>
reconcile

describe reports protocol version and pipe/PTY support. Lifecycle commands exchange one JSON request and response over stdin/stdout. exec gives file descriptors 0–2 to the workload, receives a newline-delimited spawn envelope on fd 3, and emits ordered started → eof → exit events on fd 4. PTY resize and signal controls also use fd 3.

The important invariants are deliberately small:

• validate protocol version and strict schemas;
• make workspace lifecycle operations idempotent;
• identify resources by workspaceId and the opaque runtimeInstanceId;
• execute the supplied argv directly with the supplied environment;
• never inherit daemon or wrapper environment accidentally;
• reject workspace-relative traversal and symlink escapes;
• forward signals and perform bounded cleanup of the exact execution;
• provide paseo-workspace-helper inside the runtime environment.

The complete executable schema and byte-level framing examples live in packages/workspace-runtime-contract.

Registration example

{
  "workspaceRuntimes": {
    "docker": {
      "type": "command",
      "label": "Docker",
      "command": ["/absolute/path/to/runtime-executable"],
      "options": {
        "image": "my-workspace-image:dev",
        "bindMounts": []
      }
    },
    "sandboxed": {
      "type": "command",
      "label": "Sandboxed",
      "command": ["/absolute/path/to/another-runtime"],
      "options": {
        "policy": "strict"
      }
    }
  }
}

Both entries are identical to Paseo: registered command runtimes with an ID, label, command argv, and opaque options. Their implementation details are entirely outside core.

Goals

• Preserve the Local and Worktree user experience while moving workspace execution behind one runtime surface.
• Make container, sandbox, VM, and remote-workspace implementations possible without adding their concepts to Paseo core.
• Keep the public contract and official workspace helper stable, narrow, independently testable, and suitable for external runtime repositories.
• Let New Workspace select a registered runtime and discover its actual providers before creation.
• Keep setup progress, failure, cancellation, and agent concurrency consistent across runtime implementations.
• Maintain wire compatibility: workspace ID is authoritative when supplied; older cwd-based requests remain supported at protocol edges.

Non-goals

• Ship, publish, or automatically register an external runtime implementation in Paseo releases.
• Make claims about the security, isolation, networking, credentials, or policy of a particular runtime.
• Add Docker-, sandbox-, cloud-, or provider-specific configuration to Paseo core.
• Turn the runtime CLI into a general daemon RPC or arbitrary host capability API.
• Change established Local or Worktree behavior.

Package and deletion boundary

Production server, CLI, Desktop, release, and daemon-image packages depend only on the contract and helper. Optional runtime implementations are not production dependencies and are not automatically registered.

The repository retains one private generic fixture for executable contract tests. Removing any external runtime repository leaves Paseo production coherent; removing runtime support from Paseo is localized to the contract/helper, generic registration, and workspace-runtime consumers rather than implementation-specific branches.

Related work

Refs #2453. That work explores a specific bundled container workflow; this PR provides the generic boundary but does not ship or supersede a runtime implementation.

[greptile-apps]

Too many files changed for review (336 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.