Add pluggable workspace runtimes

.github/ci-paths.yml

@@ -35,6 +35,9 @@ hub:
 
 server:
   - "packages/server/**"
+  - "runtimes/fixture/**"
+  - "packages/workspace-helper/**"
+  - "packages/workspace-runtime-contract/**"
   - "packages/app/e2e/support/fixtures/recording.*"
 
 desktop:

.github/workflows/ci.yml

@@ -102,6 +102,9 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: Enforce workspace runtime ownership boundaries
+        run: npm run check:workspace-runtime-boundaries && node --test scripts/workspace-runtime-boundaries.test.mjs
+
   typecheck:
     name: typecheck
     needs: changes
@@ -129,6 +132,8 @@ jobs:
       - name: Verify public package contents
         run: |
           npm pack --dry-run --ignore-scripts --workspace=@getpaseo/protocol
+          npm pack --dry-run --ignore-scripts --workspace=@getpaseo/workspace-runtime-contract
+          npm pack --dry-run --ignore-scripts --workspace=@getpaseo/workspace-helper
           npm pack --dry-run --ignore-scripts --workspace=@getpaseo/client
           npm pack --dry-run --ignore-scripts --workspace=@getpaseo/server
 
@@ -163,6 +168,18 @@ jobs:
       - name: Build server dependencies
         run: npm run build:server-deps
 
+      - name: Test workspace runtime command contract package
+        if: ${{ needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false' }}
+        run: npm test --workspace=@getpaseo/workspace-runtime-contract && npm test --workspace=@getpaseo/workspace-helper
+
+      - name: Prove the command runtime fixture is independently installable
+        if: ${{ runner.os == 'Linux' && (needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false') }}
+        run: node --test scripts/workspace-runtime-standalone.test.mjs
+
+      - name: Prove clean server builds own public prerequisites
+        if: ${{ runner.os == 'Linux' && (needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false') }}
+        run: node --test scripts/server-clean-build.test.mjs
+
       - name: Run server tests
         if: ${{ needs.changes.outputs.full != 'false' || needs.changes.outputs.server != 'false' }}
         run: npm run test --workspace=@getpaseo/server

.github/workflows/docker.yml

@@ -16,6 +16,9 @@ on:
       - "packages/app/**"
       - "packages/cli/**"
       - "packages/client/**"
+      - "packages/desktop/**"
+      - "packages/workspace-helper/**"
+      - "packages/workspace-runtime-contract/**"
       - "packages/expo-two-way-audio/**"
       - "packages/highlight/**"
       - "packages/plugin/**"

.oxlintrc.json

@@ -84,6 +84,144 @@
     "max-nested-callbacks": ["error", { "max": 3 }]
   },
   "overrides": [
+    {
+      "files": ["packages/server/src/**/*.{ts,tsx}"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": [
+                  "**/workspace-runtime/internal/**",
+                  "**/workspace-runtime/command/internal/**"
+                ],
+                "message": "Workspace runtime internals are owned by their public entry points."
+              },
+              {
+                "group": ["**/workspace-helper/internal/**"],
+                "message": "Normal callers consume WorkspaceFiles from workspace-helper/index. Only the workspace-runtime parent integration and workspace-helper tests may assemble helper clients."
+              },
+              {
+                "group": [
+                  "**/workspace-runtime/integration/**",
+                  "**/workspace-runtime/git-observation/internal/**"
+                ],
+                "message": "Git callers consume workspace-runtime/git-observation/index. Only runtime internals may assemble shared observation identity, placement, helpers, and lifecycle."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "packages/server/src/server/workspace-runtime/index.ts",
+        "packages/server/src/server/workspace-runtime/command/index.ts",
+        "packages/server/src/server/workspace-runtime/command/internal/**/*.{ts,tsx}",
+        "packages/server/src/server/workspace-runtime/internal/**/*.{ts,tsx}",
+        "packages/server/src/server/workspace-helper/**/*.{ts,tsx}",
+        "packages/server/src/server/workspace-runtime/git-observation/**/*.{ts,tsx}",
+        "packages/server/src/server/workspace-runtime/internal/service.ts"
+      ],
+      "rules": {
+        "no-restricted-imports": "off"
+      }
+    },
+    {
+      "files": [
+        "packages/server/src/server/session/files/**/*.{ts,tsx}",
+        "packages/server/src/server/session/git-mutation/**/*.{ts,tsx}",
+        "packages/server/src/server/session/provider/**/*.{ts,tsx}",
+        "packages/server/src/server/session/workspace-git-observer/**/*.{ts,tsx}",
+        "packages/server/src/server/session/workspace-provisioning/**/*.{ts,tsx}",
+        "packages/server/src/server/session/workspace-scripts/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              { "name": "child_process", "message": "Use the bound workspace runtime." },
+              { "name": "node:child_process", "message": "Use the bound workspace runtime." },
+              { "name": "fs", "message": "Use the bound workspace runtime." },
+              { "name": "node:fs", "message": "Use the bound workspace runtime." },
+              { "name": "fs/promises", "message": "Use the bound workspace runtime." },
+              { "name": "node:fs/promises", "message": "Use the bound workspace runtime." },
+              { "name": "module", "message": "Dynamic loaders bypass workspace ownership." },
+              {
+                "name": "node:module",
+                "message": "Dynamic loaders bypass workspace ownership."
+              },
+              { "name": "which", "message": "Use the bound workspace runtime." }
+            ],
+            "patterns": [
+              {
+                "group": ["**/utils/run-git-command.{js,ts}"],
+                "message": "Use the bound workspace runtime."
+              },
+              {
+                "group": [
+                  "**/workspace-runtime/internal/**",
+                  "**/workspace-runtime/command/internal/**",
+                  "**/workspace-runtime/git-observation/internal/**",
+                  "**/workspace-helper/internal/**"
+                ],
+                "message": "Use the owning public entry point."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "packages/server/src/server/session/files/**/*.test.{ts,tsx}",
+        "packages/server/src/server/session/git-mutation/**/*.test.{ts,tsx}",
+        "packages/server/src/server/session/provider/**/*.test.{ts,tsx}",
+        "packages/server/src/server/session/workspace-git-observer/**/*.test.{ts,tsx}",
+        "packages/server/src/server/session/workspace-provisioning/**/*.test.{ts,tsx}",
+        "packages/server/src/server/session/workspace-scripts/**/*.test.{ts,tsx}"
+      ],
+      "rules": {
+        "no-restricted-imports": "off"
+      }
+    },
+    {
+      "files": ["packages/fixture-workspace-runtime/**/*.{js,mjs,ts,tsx}"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "module",
+                "message": "The external runtime may not construct dynamic module loaders."
+              },
+              {
+                "name": "node:module",
+                "message": "The external runtime may not construct dynamic module loaders."
+              },
+              {
+                "name": "@getpaseo/server",
+                "message": "The external runtime may consume only the published command contract."
+              }
+            ],
+            "patterns": [
+              {
+                "group": [
+                  "@getpaseo/server/**",
+                  "**/packages/server/**",
+                  "**/workspace-runtime/**/internal/**",
+                  "**/workspace-helper/**/internal/**"
+                ],
+                "message": "The external runtime may consume only the published command contract."
+              }
+            ]
+          }
+        ]
+      }
+    },
     {
       "files": ["packages/app/src/**/*.{ts,tsx}"],
       "rules": {

docker/base/Dockerfile

@@ -22,6 +22,8 @@ RUN set -eux; \
     npm pack --workspace=@getpaseo/highlight --pack-destination /tmp/paseo-packs; \
     npm pack --workspace=@getpaseo/relay --pack-destination /tmp/paseo-packs; \
     npm pack --workspace=@getpaseo/protocol --pack-destination /tmp/paseo-packs; \
+    npm pack --workspace=@getpaseo/workspace-runtime-contract --pack-destination /tmp/paseo-packs; \
+    npm pack --workspace=@getpaseo/workspace-helper --pack-destination /tmp/paseo-packs; \
     npm pack --workspace=@getpaseo/client --pack-destination /tmp/paseo-packs; \
     npm pack --workspace=@paseo/plugin --pack-destination /tmp/paseo-packs; \
     npm pack --workspace=@getpaseo/server --pack-destination /tmp/paseo-packs; \

docs/architecture.md

@@ -75,6 +75,8 @@ not retain non-Git directories.
 | `server/agent/tools/`           | Transport-neutral catalog for workspaces, agents, permissions, and automation |
 | `server/agent/mcp-server.ts`    | Thin MCP adapter that registers the Paseo tool catalog with the MCP SDK       |
 | `server/agent/providers/`       | Provider adapters (see "Agent providers" below)                               |
+| `server/workspace-runtime/`     | Runtime-neutral workspace lifecycle, execution, files, Git observation        |
+| `server/provider-probe/`        | Invisible runtime-bound workspaces for pre-creation provider discovery        |
 | `server/relay-transport.ts`     | Outbound relay connection with E2E encryption                                 |
 | `server/schedule/`              | Cron-based scheduled agents                                                   |
 
@@ -85,6 +87,19 @@ agent timeline types, provider config schemas, and other values shared by daemon
 and clients. Server, app, CLI, and `@getpaseo/client` all depend on this package;
 it does not depend on the server.
 
+### Workspace runtime packages
+
+`packages/workspace-runtime-contract` owns the versioned command-runtime lifecycle and exec wire
+contract. `packages/workspace-helper` owns the official confined files/watch/command-resolution
+executable and its typed binding. The daemon depends on those two packages and registers command
+runtimes without importing an implementation.
+
+`runtimes/fixture` is a private generic contract fixture. Runtime implementations live in their own
+repositories and depend on published versions of the two public workspace packages. CLI, Desktop,
+server, release workflows, and the daemon image do not depend on, bundle, publish, or register an
+implementation. Tests invoke registered runtimes through their public command, never through source
+imports.
+
 ### `packages/client` — Daemon client library and SDK facade
 
 Owns the low-level daemon WebSocket driver plus the higher-level `PaseoClient`