lael-labs/executor

bun.lock+1−4

         "@executor-js/react": "workspace:*",
         "@executor-js/runtime-quickjs": "workspace:*",
         "@modelcontextprotocol/ext-apps": "^1.7.4",
-        "@modelcontextprotocol/sdk": "^1.29.0",
+        "@modelcontextprotocol/sdk": "^1.12.1",
         "@tanstack/react-query": "^5.99.0",
         "effect": "catalog:",
         "esbuild": "^0.27.7",
         "@effect/platform-node": "catalog:",
         "@executor-js/config": "workspace:*",
         "@executor-js/sdk": "workspace:*",
-        "@modelcontextprotocol/client": "2.0.0",
-        "@modelcontextprotocol/core": "2.0.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "zod": "4.3.6",
       },
         "@effect/vitest": "catalog:",
         "@executor-js/api": "workspace:*",
         "@executor-js/react": "workspace:*",
-        "@modelcontextprotocol/server": "2.0.0",
         "@types/node": "catalog:",
         "@types/react": "catalog:",
         "bun-types": "catalog:",

e2e/local/stdio-mcp.test.ts+0−30

@@ -146,36 +146,6 @@ scenario( · 145 unmodified lines
146	declTools.map((t) => t.name),	146	declTools.map((t) => t.name),
147	"connecting with the secret discovers the env-gated tool",	147	"connecting with the secret discovers the env-gated tool",
148	).toContain("whoami");	148	).toContain("whoami");
149
150	// --- versionNegotiation "auto" survives the API → config → connector
151	// path and still reaches a legacy server: the probe gets the fixture's
152	// method-not-found for `server/discover` (a definitive legacy verdict)
153	// and falls back to `initialize`. Modern-era acceptance against a real
154	// legacy-disabled SDK v2 server lives in the plugin's
155	// stdio-negotiation.test.ts. ---
156	const autoSlug = "e2e-stdio-auto";
157	yield* client.mcp.addServer({
158	payload: {
159	transport: "stdio",
160	name: "E2E Stdio Auto",
161	command: "node",
162	args: [FIXTURE],
163	versionNegotiation: "auto",
164	slug: autoSlug,
165	},
166	});
167
168	const autoStored = yield* client.mcp.getServer({ params: { slug: autoSlug } });
169	expect(
170	JSON.stringify(autoStored?.config ?? {}),
171	"the negotiation mode is persisted on the integration config",
172	).toContain('"versionNegotiation":"auto"');
173
174	const autoTools = yield* client.tools.list({ query: { integration: autoSlug } });
175	expect(
176	autoTools.map((t) => t.name),
177	"auto negotiation falls back to legacy and still discovers tools",
178	).toContain("echo_tool");
179	}),	149	}),
180	);	150	);
181	}),	151	}),

packages/hosts/mcp-apps-shell/package.json+1−1

@@ -69,7 +69,7 @@ · 68 unmodified lines
69	"@executor-js/react": "workspace:*",	69	"@executor-js/react": "workspace:*",
70	"@executor-js/runtime-quickjs": "workspace:*",	70	"@executor-js/runtime-quickjs": "workspace:*",
71	"@modelcontextprotocol/ext-apps": "^1.7.4",	71	"@modelcontextprotocol/ext-apps": "^1.7.4",
72	"@modelcontextprotocol/sdk": "^1.29.0",	72	"@modelcontextprotocol/sdk": "^1.12.1",
73	"@tanstack/react-query": "^5.99.0",	73	"@tanstack/react-query": "^5.99.0",
74	"effect": "catalog:",	74	"effect": "catalog:",
75	"esbuild": "^0.27.7",	75	"esbuild": "^0.27.7",

packages/plugins/mcp/package.json+0−3

     "@effect/platform-node": "catalog:",
     "@executor-js/config": "workspace:*",
     "@executor-js/sdk": "workspace:*",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/core": "2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "4.3.6"
   },
     "@effect/vitest": "catalog:",
     "@executor-js/api": "workspace:*",
     "@executor-js/react": "workspace:*",
-    "@modelcontextprotocol/server": "2.0.0",
     "@types/node": "catalog:",
     "@types/react": "catalog:",
     "bun-types": "catalog:",

packages/plugins/mcp/src/api/group.ts+0−4

   /** One-shot secret env values (programmatic). The UI sends `envVars`. */
   env: Schema.optional(StringMap),
   cwd: Schema.optional(Schema.String),
-  /** Protocol negotiation at connect: `auto` probes `server/discover` (spec
-   *  2026-07-28) for modern-only servers; default is the legacy `initialize`
-   *  handshake. */
-  versionNegotiation: Schema.optional(Schema.Literals(["legacy", "auto"])),
   slug: Schema.optional(Schema.String),
 });

packages/plugins/mcp/src/api/handlers.ts+0−2

       envVars?: readonly string[];
       env?: Record<string, string>;
       cwd?: string;
-      versionNegotiation?: "legacy" | "auto";
       slug?: string;
     };
     return {
       envVars: p.envVars ? [...p.envVars] : undefined,
       env: p.env,
       cwd: p.cwd,
-      versionNegotiation: p.versionNegotiation,
       slug: p.slug,
     };
   }

packages/plugins/mcp/src/sdk/connection-pool.ts+0−4

@@ -3,10 +3,6 @@ import { Cause, Effect, Exit, Predicate } from "effect"; · 2 unmodified lines
3	import type { McpConnection, McpConnector } from "./connection";	3	import type { McpConnection, McpConnector } from "./connection";
4	import type { McpInvocationError } from "./errors";	4	import type { McpInvocationError } from "./errors";
5		5
6	// The pool preserves sessions for sessionful legacy servers. Stateless
7	// 2026-07-28 servers do not need it, but retaining a cheap idle client is
8	// harmless and keeps one lifecycle for both protocol eras.
9
10	const IDLE_TTL_MS = 5 * 60 * 1_000;	6	const IDLE_TTL_MS = 5 * 60 * 1_000;
11		7
12	type IdleConnection = {	8	type IdleConnection = {

packages/plugins/mcp/src/sdk/connection.ts+11−35

-import {
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
-  Client,
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-  SSEClientTransport,
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-  StreamableHTTPClientTransport,
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-  type FetchLike,
+import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
-  type OAuthClientProvider,
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
-} from "@modelcontextprotocol/client";
-import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/client/validators/cf-worker";
 import { Effect, Layer, Predicate, Stream } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/unstable/http";
 // NOTE: `StdioClientTransport` is NOT imported eagerly. The upstream module
-// (`@modelcontextprotocol/client/stdio`) still imports Node process/stream and
+// (`@modelcontextprotocol/sdk/client/stdio.js`) touches `node:child_process`
-// `cross-spawn` eagerly at evaluation time, which crashes workerd (including
+// at evaluation time, which crashes workerd (incl. vitest-pool-workers) at
-// vitest-pool-workers) with SIGSEGV on module instantiation. Cloud callers set
+// SIGSEGV on module instantiation. Cloud callers set
 // `dangerouslyAllowStdioMCP: false` and never reach the stdio branch below;
 // prod bundles that DO use stdio load it via a dynamic import inside the
 // stdio branch of `createMcpConnector`.
 // MCP plugin runs inside a Cloudflare Worker (executor.sh). The
 // cfworker validator does not use code generation and works in every
 // runtime we ship to.
-const createClient = (versionNegotiation?: { readonly mode: "auto" }): Client =>
+const createClient = (): Client =>
   new Client(
     { name: "executor-mcp", version: "0.1.0" },
     {
       capabilities: { elicitation: { form: {}, url: {} } },
       jsonSchemaValidator: new CfWorkerJsonSchemaValidator(),
-      ...(versionNegotiation === undefined ? {} : { versionNegotiation }),
     },
   );
 const connectClient = (input: {
   transport: string;
   createTransport: () => Parameters<Client["connect"]>[0];
-  versionNegotiation?: { readonly mode: "auto" };
 }): Effect.Effect<McpConnection, McpConnectionError | McpOAuthReauthorizationRequired> =>
   Effect.gen(function* () {
-    const client = createClient(input.versionNegotiation);
+    const client = createClient();
     const transportInstance = input.createTransport();
     yield* Effect.tryPromise({
       catch: (cause) =>
         connectionFailure(input.transport, `Failed connecting via ${input.transport}`, cause),
     }).pipe(
-      // The negotiated era ("modern" = 2026-07-28 server/discover, "legacy" =
-      // 2025 initialize) is otherwise invisible: both eras list and call tools
-      // identically, so traces are the one place an integration author can
-      // verify which handshake a connection actually used.
-      Effect.tap(() =>
-        Effect.annotateCurrentSpan({
-          "plugin.mcp.protocol_era": client.getProtocolEra() ?? "unknown",
-        }),
-      ),
       Effect.withSpan("plugin.mcp.connection.handshake", {
         attributes: { "plugin.mcp.transport": input.transport },
       }),
       return yield* connectClient({
         transport: "stdio",
-        // Opt-in per integration (default legacy) — see
-        // `McpStdioVersionNegotiation` for why stdio does not follow the
-        // remote transport's unconditional auto.
-        ...(input.versionNegotiation === "auto"
-          ? { versionNegotiation: { mode: "auto" as const } }
-          : {}),
         createTransport: () =>
           createStdioTransport({
             command,
   const endpoint = buildEndpointUrl(input.endpoint, input.queryParams ?? {});
-  // Auto-negotiate the 2026-07-28 era unconditionally only on Streamable
-  // HTTP. SSE is a legacy-only transport; stdio negotiates per the
-  // integration's `versionNegotiation` (default legacy — see the stdio
-  // branch above).
   const connectStreamableHttp = connectClient({
     transport: "streamable-http",
-    versionNegotiation: { mode: "auto" },
     createTransport: () =>
       new StreamableHTTPClientTransport(endpoint, {
         requestInit,

packages/plugins/mcp/src/sdk/elicitation.test.ts+3−3

@@ -1,7 +1,7 @@
1	import { describe, expect, it } from "@effect/vitest";	1	import { describe, expect, it } from "@effect/vitest";
2	import { Effect, Predicate, Schema, Semaphore } from "effect";	2	import { Effect, Predicate, Schema, Semaphore } from "effect";
3	import type { JsonSchemaType } from "@modelcontextprotocol/client";	3	import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
4	import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/client/validators/cf-worker";	4	import type { JsonSchemaType } from "@modelcontextprotocol/sdk/validation/types";
5		5
6	import {	6	import {
7	AuthTemplateSlug,	7	AuthTemplateSlug,
@@ -226,7 +226,7 @@ describe("MCP elicitation (end-to-end)", () => { · 218 unmodified lines
226	]),	226	]),
227	);	227	);
228	expect(schema?.outputTypeScript).toContain('type: "text"');	228	expect(schema?.outputTypeScript).toContain('type: "text"');
229	expect(schema?.outputTypeScript).toContain("structuredContent?: unknown;");	229	expect(schema?.outputTypeScript).toContain("structuredContent?: { [k: string]: unknown; }");
230		230
231	const result = yield* executor.execute(	231	const result = yield* executor.execute(
232	simpleEcho.address,	232	simpleEcho.address,

packages/plugins/mcp/src/sdk/http-status.test.ts+3−17

 import { describe, expect, it } from "@effect/vitest";
-import { InsufficientScopeError, SdkErrorCode, SdkHttpError } from "@modelcontextprotocol/client";
 // oxlint-disable executor/no-error-constructor -- boundary: these tests reproduce the MCP SDK's own transport rejections, which are built-in Errors
 import { insufficientScopeFromCause } from "./http-status";
 //   - with an authProvider (the production OAuth path): the StreamableHTTP
 //     transport consumes the insufficient_scope challenge itself, retries
 //     with the broader scope, and only when THAT fails throws the fixed
-//     typed `InsufficientScopeError`, or after retry exhaustion the fixed
+//     "Server returned 403 after trying upscoping" message.
-//     `SdkHttpError` step-up message.
 describe("insufficientScopeFromCause", () => {
   it("detects the OAuth error body embedded in a transport message", () => {
     expect(
     ).toBe(true);
   });
-  it("detects the SDK's typed insufficient-scope failure", () => {
+  it("detects the SDK's exhausted-upscoping failure (the authProvider path)", () => {
     expect(
-      insufficientScopeFromCause(new InsufficientScopeError({ requiredScope: "files.read" })),
+      insufficientScopeFromCause(new Error("Server returned 403 after trying upscoping")),
-    ).toBe(true);
-  });
-  it("detects the SDK's exhausted step-up failure (the authProvider path)", () => {
-    expect(
-      insufficientScopeFromCause(
-        new SdkHttpError(
-          SdkErrorCode.ClientHttpForbidden,
-          "Server returned 403 insufficient_scope after step-up re-authorization (retry limit 2 reached)",
-          { status: 403 },
-        ),
-      ),
     ).toBe(true);
   });

packages/plugins/mcp/src/sdk/http-status.ts+20−25

 // ---------------------------------------------------------------------------
 // Extract the HTTP status from an MCP SDK transport error. The SDK surfaces
-// transport failures two ways: an `SdkHttpError` carrying a numeric `status`,
+// transport failures two ways: a `StreamableHTTPError` subclass carrying a
-// and an `SseError` carrying a numeric `code`. The SSE transport also retains
+// numeric `code`, and an SSE POST failure whose message embeds `(HTTP nnn)`.
-// its historic POST-failure message for errors created below EventSource.
 // Shared by the invoke path (classifies tool-call failures) and the connect
 // path (so a 401/403 during the handshake reaches the liveness health check).
 // ---------------------------------------------------------------------------
 import { Option, Schema } from "effect";
 import { insufficientScopeFromEmbeddedJson } from "@executor-js/sdk/core";
-import { InsufficientScopeError, SdkHttpError, SseError } from "@modelcontextprotocol/client";
+import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 const SsePostErrorCause = Schema.Struct({ message: Schema.String });
 const decodeSsePostErrorCause = Schema.decodeUnknownOption(SsePostErrorCause);
-// V2 still constructs this exact message in SSEClientTransport._send. A format
+// Matches the SDK's SSEClientTransport POST-failure message (sse.js); re-verify
-// drift just yields undefined (generic error, no crash).
+// on SDK bumps. A format drift just yields undefined (generic error, no crash).
 const statusFromSsePostError = (cause: unknown): number | undefined =>
   Option.match(decodeSsePostErrorCause(cause), {
     onNone: () => undefined,
     },
   });
-const statusFromTypedTransportError = (cause: unknown): number | undefined => {
+const statusFromStreamableHttpError = (cause: unknown): number | undefined => {
-  if (SdkHttpError.isInstance(cause)) return cause.status;
+  // oxlint-disable-next-line executor/no-instanceof-tagged-error -- boundary: MCP SDK exposes transport HTTP failures as this Error subclass; protocol errors can carry the same numeric code
-  if (SseError.isInstance(cause)) {
+  if (!(cause instanceof StreamableHTTPError)) return undefined;
-    const code = cause.code;
+  const code = cause.code;
-    return code !== undefined && code >= 100 && code <= 599 ? code : undefined;
+  return code !== undefined && code >= 100 && code <= 599 ? code : undefined;
-  }
-  return undefined;
 };
 export const httpStatusFromCause = (cause: unknown): number | undefined =>
-  statusFromTypedTransportError(cause) ?? statusFromSsePostError(cause);
+  statusFromStreamableHttpError(cause) ?? statusFromSsePostError(cause);
 // The SDK embeds the upstream response text in the transport error message
 // ("Error POSTing to endpoint: <body>"), which is the only place a 403's body
 // survives for connections without an authProvider. For OAuth connections the
-// StreamableHTTP transport consumes the insufficient_scope challenge itself.
+// StreamableHTTP transport consumes the insufficient_scope challenge ITSELF:
-// V2 throws `InsufficientScopeError` when configured not to reauthorize; after
+// it re-runs auth requesting the broader scope, and only when that upscoped
-// exhausting its step-up retries it throws `SdkHttpError` with the exact fixed
+// retry still 403s does it throw — with the fixed message matched below
-// message matched below (verified against the installed v2 transport source).
+// (verified against @modelcontextprotocol/sdk streamableHttp.js; re-verify on
-// Both paths mean the same thing: the grant does not cover the operation, and
+// SDK bumps). Both paths mean the same thing: the grant does not cover the
-// re-running the identical flow cannot help. Strict matching
+// operation, and re-running the identical flow cannot help. Strict matching
 // (exact serialized field forms via the shared core detector, or the SDK's
-// exact step-up message) — a miss stays on the generic auth path.
+// exact upscoping message) — a miss stays on the generic auth path.
-const SDK_STEP_UP_EXHAUSTED_RE =
+const SDK_UPSCOPING_EXHAUSTED_RE = /Server returned 403 after trying upscoping/;
-  /^Server returned 403 insufficient_scope after step-up re-authorization \(retry limit \d+ reached\)$/;
 export const insufficientScopeFromCause = (cause: unknown): boolean =>
-  InsufficientScopeError.isInstance(cause) ||
   Option.match(decodeSsePostErrorCause(cause), {
     onNone: () => false,
     onSome: ({ message }) =>
-      insufficientScopeFromEmbeddedJson(message) || SDK_STEP_UP_EXHAUSTED_RE.test(message),
+      insufficientScopeFromEmbeddedJson(message) || SDK_UPSCOPING_EXHAUSTED_RE.test(message),
   });

packages/plugins/mcp/src/sdk/invoke.test.ts+5−10

 import { Effect, Predicate } from "effect";
 import { HttpServerResponse } from "effect/unstable/http";
-import {
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
-  ProtocolError,
+import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-  SdkErrorCode,
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
-  SdkHttpError,
-  type OAuthClientProvider,
-} from "@modelcontextprotocol/client";
 import { ElicitationResponse } from "@executor-js/sdk";
 import { serveTestHttpApp } from "@executor-js/sdk/testing";
     name: "wraps callTool rejection with a stable message and status",
     toolId: "blocked",
     transport: "streamable-http",
-    cause: new SdkHttpError(SdkErrorCode.ClientHttpAuthentication, "token=do-not-leak", {
+    cause: new StreamableHTTPError(401, "token=do-not-leak"),
-      status: 401,
-    }),
     expectedStatus: 401 as number | undefined,
   },
   {
     name: "does not treat MCP protocol error codes as HTTP statuses",
     toolId: "protocol_error",
     transport: "streamable-http",
-    cause: new ProtocolError(401, "application-level do-not-leak"),
+    cause: new McpError(401, "application-level do-not-leak"),
     expectedStatus: undefined,
   },
   {

packages/plugins/mcp/src/sdk/invoke.ts+15−24

 //      legitimately retain state in that session. The pool keeps one idle
 //      connection per resolved identity and leases it exclusively per invoke;
 //      stdio and callers without a pool remain strictly per-call.
-//   2. Installing a per-invocation `elicitation/create` handler that bridges
+//   2. Installing a per-invocation `ElicitRequestSchema` handler that bridges
 //      MCP's elicit capability into the host's elicit function threaded via
 //      `InvokeToolInput.elicit`.
 //   3. Calling `client.callTool({ name, arguments })`.
 import { Cause, Effect, Exit, Option, Predicate, Schema } from "effect";
-import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/client";
+import {
+  ElicitRequestSchema,
+  ErrorCode,
+  McpError,
+  ToolListChangedNotificationSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 import {
   ElicitationId,
 const isUnknownToolCause = (cause: unknown, toolName: string): boolean =>
   // oxlint-disable-next-line executor/no-instanceof-tagged-error -- boundary: MCP SDK surfaces JSON-RPC protocol errors as this Error subclass
-  cause instanceof ProtocolError &&
+  cause instanceof McpError &&
-  (cause.code === ProtocolErrorCode.InvalidParams ||
+  (cause.code === ErrorCode.InvalidParams || cause.code === ErrorCode.MethodNotFound) &&
-    cause.code === ProtocolErrorCode.MethodNotFound) &&
+  // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: instanceof narrows to the SDK's McpError, whose message carries the only unknown-tool discriminator the protocol provides
-  // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: instanceof narrows to the SDK's ProtocolError, whose message carries the only unknown-tool discriminator the protocol provides
   isUnknownToolMessage(cause.message, toolName);
 // ---------------------------------------------------------------------------
 type McpElicitParams = typeof McpElicitParams.Type;
 const decodeElicitParams = Schema.decodeUnknownSync(McpElicitParams);
-const decodeElicitContent = Schema.decodeUnknownSync(
-  Schema.Record(
-    Schema.String,
-    Schema.Union([
-      Schema.String,
-      Schema.Number,
-      Schema.Boolean,
-      Schema.mutable(Schema.Array(Schema.String)),
-    ]),
-  ),
-);
 const toElicitationRequest = (params: McpElicitParams): ElicitationRequest =>
   params.mode === "url"
       });
 const installElicitationHandler = (client: McpConnection["client"], elicit: Elicit): void => {
-  client.setRequestHandler("elicitation/create", async (request: { params: unknown }) => {
+  client.setRequestHandler(ElicitRequestSchema, async (request: { params: unknown }) => {
     const params = decodeElicitParams(request.params);
     const req = toElicitationRequest(params);
     // Use runPromiseExit so we can inspect typed failures — `elicit`
       const response = exit.value;
       return {
         action: response.action,
-        ...(response.action === "accept" && response.content
+        ...(response.action === "accept" && response.content ? { content: response.content } : {}),
-          ? { content: decodeElicitContent(response.content) }
-          : {}),
       };
     }
     const failure = exit.cause.reasons.find(Cause.isFailReason);
   onToolListChanged: (() => void) | undefined,
 ): void => {
   if (!onToolListChanged) return;
-  client.setNotificationHandler("notifications/tools/list_changed", () => {
+  client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
     onToolListChanged();
   });
 };
           });
         }
         const status = httpStatusFromCause(cause);
-        // oxlint-disable-next-line executor/no-instanceof-tagged-error -- boundary: MCP SDK protocol failures are its ProtocolError subclass; transport failures use other error shapes
+        // oxlint-disable-next-line executor/no-instanceof-tagged-error -- boundary: MCP SDK protocol failures are its McpError subclass; transport failures use other error shapes
-        const protocolFailure = cause instanceof ProtocolError;
+        const protocolFailure = cause instanceof McpError;
         return new McpInvocationError({
           toolName,
           message: `MCP tool call failed for ${toolName}`,

packages/plugins/mcp/src/sdk/plugin.ts+5−15

 import { Effect, Layer, Option, Result, Schema } from "effect";
 import type { HttpClient } from "effect/unstable/http";
-import type { OAuthClientProvider } from "@modelcontextprotocol/client";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
-import { CallToolResultSchema } from "@modelcontextprotocol/core";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import * as z from "zod/v4";
 import {
   authToolFailure,
   expandMcpAuthMethodInputs,
   mcpAuthMethodFromShorthand,
   normalizeMcpAuthMethods,
-  McpStdioVersionNegotiation,
   parseMcpIntegrationConfig,
   type McpIntegrationConfig as McpIntegrationConfigType,
   type McpStdioEnvMethod,
    *  instead and leaves the values to the connect step. */
   env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   cwd: Schema.optional(Schema.String),
-  /** Protocol negotiation at connect: `auto` probes `server/discover` (spec
-   *  2026-07-28) for modern-only servers. Defaults to the legacy `initialize`
-   *  handshake — the right call for spawn-per-call servers, where the auto
-   *  probe costs an extra child process per connect. */
-  versionNegotiation: Schema.optional(McpStdioVersionNegotiation),
   slug: Schema.optional(Schema.String),
 });
       command: input.command,
       args: input.args ? [...input.args] : undefined,
       cwd: input.cwd,
-      versionNegotiation: input.versionNegotiation,
       authenticationTemplate:
         vars.length > 0
           ? [{ slug: STDIO_ENV_TEMPLATE, kind: "stdio_env", vars }]
   readonly properties?: Record<string, unknown>;
 };
-const McpCallToolResultJsonSchema: JsonSchemaObject = CallToolResultSchema.toJSONSchema();
+const McpCallToolResultJsonSchema = z.toJSONSchema(CallToolResultSchema) as JsonSchemaObject;
 const mcpCallToolResultOutputSchema = (structuredContentSchema?: unknown): JsonSchemaObject => {
   const defaultStructuredContentSchema =
 // MCP-SDK OAuth provider adapter — wraps a pre-resolved access token so the
 // transport sends it as a Bearer header. Refresh is core's responsibility
 // (the connection row carries the OAuth grant); this adapter never initiates
-// a new flow and fails loudly if the SDK tries to. V2 stamps stored credentials
+// a new flow and fails loudly if the SDK tries to.
-// with the authorization-server issuer and offers scoped invalidation; this
-// single-token boundary intentionally persists neither.
 // ---------------------------------------------------------------------------
 const makeOAuthProvider = (accessToken: string): OAuthClientProvider => ({
       args: config.args,
       env: Object.keys(env).length > 0 ? env : undefined,
       cwd: config.cwd,
-      versionNegotiation: config.versionNegotiation,
     } satisfies McpStdioIntegrationConfig);
   }
                 command: config.command,
                 args: config.args,
                 cwd: config.cwd,
-                versionNegotiation: config.versionNegotiation,
                 authenticationTemplate: hasEnv
                   ? [{ slug: STDIO_ENV_TEMPLATE, kind: "stdio_env", vars: envVars }]
                   : [{ slug: "none", kind: "none" }],

packages/plugins/mcp/src/sdk/probe-shape.test.ts+2−90

@@ -1,12 +1,6 @@
1	import { describe, expect, it } from "@effect/vitest";	1	import { describe, expect, it } from "@effect/vitest";
2	import { Effect, Layer, Ref } from "effect";	2	import { Effect, Ref } from "effect";
3	import {	3	import { HttpServerResponse } from "effect/unstable/http";
4	HttpClient,
5	HttpClientError,
6	HttpClientRequest,
7	HttpClientResponse,
8	HttpServerResponse,
9	} from "effect/unstable/http";
10	import { serveTestHttpApp } from "@executor-js/sdk/testing";	4	import { serveTestHttpApp } from "@executor-js/sdk/testing";
11		5
12	import { probeMcpEndpointShape } from "./probe-shape";	6	import { probeMcpEndpointShape } from "./probe-shape";
@@ -326,88 +320,6 @@ describe("probeMcpEndpointShape", () => { · 313 unmodified lines
326	),	320	),
327	);	321	);
328		322
329	it.effect("falls through a wrong-shape legacy GET retry to modern server discovery", () =>
330	Effect.scoped(
331	Effect.gen(function* () {
332	const server = yield* serveProbeEndpoint((request) => {
333	if (request.body.includes('"method":"server/discover"')) {
334	return HttpServerResponse.jsonUnsafe({
335	jsonrpc: "2.0",
336	id: 2,
337	error: { code: -32601, message: "Method not found" },
338	});
339	}
340	if (request.method === "GET") {
341	return HttpServerResponse.jsonUnsafe({ error: "legacy SSE is unsupported" });
342	}
343	return HttpServerResponse.empty({ status: 405 });
344	});
345
346	const result = yield* probeMcpEndpointShape(server.endpoint);
347	expect(result).toEqual({ kind: "mcp", requiresAuth: false });
348
349	const requests = yield* server.requests;
350	expect(requests).toHaveLength(3);
351	expect(requests[0]?.body).toContain('"protocolVersion":"2025-11-25"');
352	expect(requests[1]?.method).toBe("GET");
353	expect(requests[2]?.body).toBe(
354	JSON.stringify({
355	jsonrpc: "2.0",
356	id: 2,
357	method: "server/discover",
358	params: {
359	_meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" },
360	},
361	}),
362	);
363	expect(requests[2]?.headers["mcp-protocol-version"]).toBe("2026-07-28");
364	}),
365	),
366	);
367
368	// First request (initialize) answers 200 HTML; second (the discover
369	// fallback) dies at the transport. The endpoint already proved reachable,
370	// so the verdict must stay the initialize classification, not "unreachable".
371	it.effect("keeps the initialize verdict when the discover fallback fails at the transport", () =>
372	Effect.gen(function* () {
373	let requestCount = 0;
374	const httpClientLayer = Layer.succeed(HttpClient.HttpClient)(
375	HttpClient.make((request: HttpClientRequest.HttpClientRequest) => {
376	requestCount += 1;
377	if (requestCount > 1) {
378	return Effect.fail(
379	new HttpClientError.HttpClientError({
380	reason: new HttpClientError.TransportError({
381	request,
382	description: "connection reset by peer",
383	}),
384	}),
385	);
386	}
387	return Effect.succeed(
388	HttpClientResponse.fromWeb(
389	request,
390	new Response("<html>not mcp</html>", {
391	status: 200,
392	headers: { "content-type": "text/html" },
393	}),
394	),
395	);
396	}),
397	);
398
399	const result = yield* probeMcpEndpointShape("https://internal.example/mcp", {
400	httpClientLayer,
401	});
402	expect(result).toEqual({
403	kind: "not-mcp",
404	category: "wrong-shape",
405	reason: "2xx POST body is not a JSON-RPC envelope",
406	});
407	expect(requestCount).toBe(2);
408	}),
409	);
410
411	it.effect("rejects 2xx with HTML body as wrong-shape", () =>	323	it.effect("rejects 2xx with HTML body as wrong-shape", () =>
412	withServer(	324	withServer(
413	() =>	325	() =>

packages/plugins/mcp/src/sdk/probe-shape.ts+10−51

 //   and (b) plenty of real MCP servers authenticate with static API
 //   keys and publish no OAuth metadata at all (e.g. cubic.dev).
 //
-// The primary probe issues an unauth JSON-RPC `initialize` POST and accepts
+// The probe issues an unauth JSON-RPC `initialize` POST and accepts
 // only the wire shapes a real MCP server can return:
 //
 //   - 2xx with `Content-Type: text/event-stream` — streamable HTTP
 // only accepts 2xx with `text/event-stream` or the same 401+Bearer
 // shape.
 //
-// If initialize ultimately has the wrong shape, a second JSON-RPC POST probes
+// One `fetch` (occasionally two), no MCP-SDK session state, no OAuth
-// `server/discover` using the 2026-07-28 envelope and protocol header. This
+// round-trip, no DCR — every non-MCP endpoint exits here.
-// catches modern-only servers that reject initialize with a non-JSON-RPC
-// response. Authentication outcomes remain terminal because they do not vary
-// by transport era.
-//
-// One primary request (occasionally plus legacy GET and modern discover), no
-// MCP-SDK session state, no OAuth round-trip, no DCR.
 // ---------------------------------------------------------------------------
 import { Data, Duration, Effect, Layer, Option, Schema } from "effect";
   id: 1,
   method: "initialize",
   params: {
-    protocolVersion: "2025-11-25",
+    protocolVersion: "2025-06-18",
     capabilities: {},
     clientInfo: { name: "executor-probe", version: "0" },
   },
 });
-const DISCOVER_BODY = JSON.stringify({
-  jsonrpc: "2.0",
-  id: 2,
-  method: "server/discover",
-  params: {
-    _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" },
-  },
-});
 /** Header-name lookup is case-insensitive per RFC 7230. `fetch`'s
  *  `Response.headers` already lower-cases, but we normalise explicitly
  *  to stay robust against test mocks that construct `Headers` loosely. */
         .execute(postRequest)
         .pipe(Effect.timeout(Duration.millis(timeoutMs)));
-      let initializeResult = yield* classify(postResponse, "POST");
+      const postResult = yield* classify(postResponse, "POST");
+      if (postResult) return postResult;
-      if (initializeResult === null && [404, 405, 406, 415].includes(postResponse.status)) {
+      if ([404, 405, 406, 415].includes(postResponse.status)) {
         let getRequest = HttpClientRequest.get(url.toString()).pipe(
           HttpClientRequest.setHeader("accept", "text/event-stream"),
         );
         const getResponse = yield* client
           .execute(getRequest)
           .pipe(Effect.timeout(Duration.millis(timeoutMs)));
-        initializeResult = yield* classify(getResponse, "GET");
+        const getResult = yield* classify(getResponse, "GET");
+        if (getResult) return getResult;
       }
-      initializeResult ??= {
+      return {
         kind: "not-mcp",
         category: "wrong-shape",
         reason: `unexpected status ${postResponse.status} for initialize`,
       } as const;
-      if (initializeResult.kind !== "not-mcp" || initializeResult.category !== "wrong-shape") {
-        return initializeResult;
-      }
-      let discoverRequest = HttpClientRequest.post(url.toString()).pipe(
-        HttpClientRequest.setHeader("content-type", "application/json"),
-        HttpClientRequest.setHeader("accept", "application/json, text/event-stream"),
-        HttpClientRequest.bodyText(DISCOVER_BODY, "application/json"),
-      );
-      for (const [name, value] of Object.entries(options.headers ?? {})) {
-        discoverRequest = HttpClientRequest.setHeader(discoverRequest, name, value);
-      }
-      discoverRequest = HttpClientRequest.setHeader(
-        discoverRequest,
-        "MCP-Protocol-Version",
-        "2026-07-28",
-      );
-      // The endpoint already answered the primary probe, so a transport
-      // failure on this secondary request must not overwrite that verdict
-      // with "unreachable" — keep the initialize classification instead.
-      const discoverResult = yield* client.execute(discoverRequest).pipe(
-        Effect.timeout(Duration.millis(timeoutMs)),
-        Effect.flatMap((discoverResponse) => classify(discoverResponse, "POST")),
-        Effect.catch(() => Effect.succeed(null)),
-      );
-      return discoverResult ?? initializeResult;
     }).pipe(
       Effect.provide(options.httpClientLayer ?? FetchHttpClient.layer),
       Effect.mapError(

packages/plugins/mcp/src/sdk/stdio-connector.ts+3−4

 // ---------------------------------------------------------------------------
 //
 // Kept in its own module so `connection.ts` never imports it eagerly at
-// module load. The v2 `@modelcontextprotocol/client/stdio` entry still eagerly
+// module load. `@modelcontextprotocol/sdk/client/stdio.js` pulls in
-// evaluates Node-only process/stream imports and `cross-spawn` (which loads
+// `node:child_process` at evaluation time; under `@cloudflare/vitest-pool-workers`
-// `node:child_process`); under `@cloudflare/vitest-pool-workers`
 // that crashes workerd at module instantiation with SIGSEGV (prod bundles
 // tree-shake it away when `dangerouslyAllowStdioMCP: false`, tests do not).
 //
 // the import and therefore never touch `node:child_process`.
 // ---------------------------------------------------------------------------
-import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 export type StdioTransportConfig = {
   readonly command: string;

packages/plugins/mcp/src/sdk/stdio-negotiation-test-server.ts+0−24

@@ -1,24 +0,0 @@
1	// Stdio MCP fixture for stdio-negotiation.test.ts, spawned as a child process
2	// with `bun run <this file>`. Serves both protocol eras by default;
3	// `--legacy-reject` refuses the 2025 `initialize` opening so only a client
4	// probing `server/discover` (spec 2026-07-28) can connect — the shape of an
5	// SDK v2 server running with its legacy compatibility lane disabled.
6	import { McpServer } from "@modelcontextprotocol/server";
7	import { serveStdio } from "@modelcontextprotocol/server/stdio";
8	import * as z from "zod/v4";
9
10	serveStdio(
11	() => {
12	const server = new McpServer(
13	{ name: "stdio-negotiation-fixture", version: "1.0.0" },
14	{ capabilities: { tools: {} } },
15	);
16	server.registerTool(
17	"add",
18	{ description: "Add two numbers", inputSchema: z.object({ a: z.number(), b: z.number() }) },
19	async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }),
20	);
21	return server;
22	},
23	{ legacy: process.argv.includes("--legacy-reject") ? "reject" : "serve" },
24	);

packages/plugins/mcp/src/sdk/stdio-negotiation.test.ts+0−64

@@ -1,64 +0,0 @@
1	import { describe, expect, it } from "@effect/vitest";
2	import { Effect, Predicate } from "effect";
3	import { fileURLToPath } from "node:url";
4
5	import { createMcpConnector, type StdioConnectorInput } from "./connection";
6
7	const fixture = fileURLToPath(new URL("./stdio-negotiation-test-server.ts", import.meta.url));
8
9	const stdioInput = (
10	overrides: Partial<Omit<StdioConnectorInput, "transport" \| "command">> & {
11	readonly args: readonly string[];
12	},
13	): StdioConnectorInput => ({
14	transport: "stdio",
15	command: "bun",
16	...overrides,
17	});
18
19	const withConnection = (input: StdioConnectorInput) =>
20	Effect.acquireRelease(createMcpConnector(input).pipe(Effect.orDie), (connection) =>
21	Effect.promise(connection.close),
22	);
23
24	describe("stdio version negotiation", () => {
25	it.effect("auto negotiation connects modern to a server with legacy support disabled", () =>
26	Effect.scoped(
27	Effect.gen(function* () {
28	const connection = yield* withConnection(
29	stdioInput({ args: ["run", fixture, "--legacy-reject"], versionNegotiation: "auto" }),
30	);
31
32	expect(connection.client.getProtocolEra()).toBe("modern");
33	const tools = yield* Effect.promise(() => connection.client.listTools());
34	expect(tools.tools.map(({ name }) => name)).toContain("add");
35	const result = yield* Effect.promise(() =>
36	connection.client.callTool({ name: "add", arguments: { a: 2, b: 2 } }),
37	);
38	expect(result.content).toEqual([{ type: "text", text: "4" }]);
39	}),
40	),
41	);
42
43	it.effect("the default handshake surfaces a connection error on that same server", () =>
44	Effect.gen(function* () {
45	const error = yield* createMcpConnector(
46	stdioInput({ args: ["run", fixture, "--legacy-reject"] }),
47	).pipe(Effect.flip);
48
49	expect(Predicate.isTagged(error, "McpConnectionError")).toBe(true);
50	}),
51	);
52
53	it.effect("absent config keeps the legacy handshake against a both-era server", () =>
54	Effect.scoped(
55	Effect.gen(function* () {
56	const connection = yield* withConnection(stdioInput({ args: ["run", fixture] }));
57
58	expect(connection.client.getProtocolEra()).toBe("legacy");
59	const tools = yield* Effect.promise(() => connection.client.listTools());
60	expect(tools.tools.map(({ name }) => name)).toContain("add");
61	}),
62	),
63	);
64	});

packages/plugins/mcp/src/sdk/testing-fixtures.test.ts+3−5

 import { expect, layer } from "@effect/vitest";
 import { Effect } from "effect";
-import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { OAuthTestServer } from "@executor-js/sdk/testing";
 import { makeEchoMcpServer, serveMcpServerWithOAuth } from "../testing";
   });
 const makeClient = (endpoint: string, accessToken: string) => {
-  const client = new Client(
+  const client = new Client({ name: "executor-test-client", version: "1.0.0" });
-    { name: "executor-test-client", version: "1.0.0" },
-    { versionNegotiation: { mode: "auto" } },
-  );
   const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
     requestInit: {
       headers: { authorization: `Bearer ${accessToken}` },

packages/plugins/mcp/src/sdk/types.ts+0−17

@@ -31,20 +31,6 @@ export type McpRemoteTransport = typeof McpRemoteTransport.Type; · 30 unmodified lines
31	export const McpTransport = Schema.Literals(["streamable-http", "sse", "stdio", "auto"]);	31	export const McpTransport = Schema.Literals(["streamable-http", "sse", "stdio", "auto"]);
32	export type McpTransport = typeof McpTransport.Type;	32	export type McpTransport = typeof McpTransport.Type;
33		33
34	/** Protocol-version negotiation for a stdio server, mirroring the client
35	* SDK's `versionNegotiation` modes. `legacy` (the default when absent) opens
36	* with the 2025 `initialize` handshake; `auto` probes `server/discover`
37	* (spec 2026-07-28) and falls back to `initialize` on legacy servers.
38	*
39	* Deliberately opt-in, unlike remote streamable HTTP where `auto` is
40	* unconditional: the SDK's stdio probe runs on a short-lived sibling
41	* process, and a legacy server that never answers the probe stalls connect
42	* for the full probe timeout — the wrong default for spawn-per-call CLI
43	* servers, and exactly the case the SDK's own guidance says to keep on the
44	* legacy handshake unless the server is known-modern. */
45	export const McpStdioVersionNegotiation = Schema.Literals(["legacy", "auto"]);
46	export type McpStdioVersionNegotiation = typeof McpStdioVersionNegotiation.Type;
47
48	// ---------------------------------------------------------------------------	34	// ---------------------------------------------------------------------------
49	// Auth methods — the shared placements vocabulary (`@executor-js/sdk/http-auth`)	35	// Auth methods — the shared placements vocabulary (`@executor-js/sdk/http-auth`)
50	// plus MCP's own oauth variant. An integration declares zero or more methods,	36	// plus MCP's own oauth variant. An integration declares zero or more methods,
@@ -222,9 +208,6 @@ export const McpStdioIntegrationConfig = Schema.Struct({ · 171 unmodified lines
222	env: Schema.optional(StringMap),	208	env: Schema.optional(StringMap),
223	/** Working directory */	209	/** Working directory */
224	cwd: Schema.optional(Schema.String),	210	cwd: Schema.optional(Schema.String),
225	/** Protocol negotiation at connect. Absent means `legacy` (see
226	* `McpStdioVersionNegotiation` for why that stays the default). */
227	versionNegotiation: Schema.optional(McpStdioVersionNegotiation),
228	/** Declared auth methods — a single `stdio_env` method naming the secret env	211	/** Declared auth methods — a single `stdio_env` method naming the secret env
229	* vars, or `none`. A connection's `template` picks one by slug, exactly as	212	* vars, or `none`. A connection's `template` picks one by slug, exactly as
230	* for remote servers. Optional so pre-revamp stdio configs (which had no	213	* for remote servers. Optional so pre-revamp stdio configs (which had no

packages/plugins/mcp/src/testing/server.ts+2−37

@@ -1,9 +1,8 @@
1	import { Context, Data, Effect, Layer, Option, Ref, Schema, Scope } from "effect";	1	import { Context, Data, Effect, Layer, Ref, Scope } from "effect";
2	import * as http from "node:http";	2	import * as http from "node:http";
3	// Intentionally stays on the legacy SDK as a wire-interop fixture for MCP plugin clients.	3	// Intentionally stays on the legacy SDK as a wire-interop fixture for MCP plugin clients.
4	import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";	4	import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
5	import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";	5	import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
6	import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
7	import { OAuthTestServer } from "@executor-js/sdk/testing";	6	import { OAuthTestServer } from "@executor-js/sdk/testing";
8	import z from "zod";	7	import z from "zod";
9		8
@@ -59,22 +58,6 @@ const writeText = (response: http.ServerResponse, status: number, body: string) · 49 unmodified lines
59	response.end(body);	58	response.end(body);
60	};	59	};
61		60
62	const readRequestBody = (
63	request: http.IncomingMessage,
64	): Effect.Effect<string, McpTestServerError> =>
65	Effect.tryPromise({
66	try: () =>
67	new Promise<string>((resolve, reject) => {
68	const chunks: Buffer[] = [];
69	request.on("data", (chunk: Buffer) => chunks.push(chunk));
70	request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
71	request.on("error", reject);
72	}),
73	catch: (cause) => new McpTestServerError({ cause }),
74	});
75
76	const decodeJsonBody = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
77
78	const isMcpPath = (url: string, path: string): boolean => {	61	const isMcpPath = (url: string, path: string): boolean => {
79	const parsed = new URL(url, "http://executor.test");	62	const parsed = new URL(url, "http://executor.test");
80	return parsed.pathname === path;	63	return parsed.pathname === path;
@@ -175,24 +158,6 @@ export const serveMcpServer = (factory: () => McpServer, options: McpTestServerO · 94 unmodified lines
175	return;	158	return;
176	}	159	}
177		160
178	// Mirror the real v1 transport's stateful contract: only an
179	// `initialize` POST opens a session; any other sessionless POST
180	// (e.g. a v2 client's `server/discover` era probe) is rejected
181	// with 400 + a JSON-RPC error and no session is minted.
182	let parsedBody: unknown;
183	if (request.method === "POST") {
184	const body = yield* readRequestBody(request);
185	parsedBody = Option.getOrUndefined(decodeJsonBody(body));
186	if (!isInitializeRequest(parsedBody)) {
187	writeJson(response, 400, {
188	jsonrpc: "2.0",
189	error: { code: -32000, message: "Bad Request: Server not initialized" },
190	id: null,
191	});
192	return;
193	}
194	}
195
196	const transport = new StreamableHTTPServerTransport({	161	const transport = new StreamableHTTPServerTransport({
197	sessionIdGenerator: () => crypto.randomUUID(),	162	sessionIdGenerator: () => crypto.randomUUID(),
198	onsessioninitialized: (sid) => {	163	onsessioninitialized: (sid) => {
@@ -208,7 +173,7 @@ export const serveMcpServer = (factory: () => McpServer, options: McpTestServerO · 9 unmodified lines
208	catch: (cause) => new McpTestServerError({ cause }),	173	catch: (cause) => new McpTestServerError({ cause }),
209	});	174	});
210	yield* Effect.tryPromise({	175	yield* Effect.tryPromise({
211	try: () => transport.handleRequest(request, response, parsedBody),	176	try: () => transport.handleRequest(request, response),
212	catch: (cause) => new McpTestServerError({ cause }),	177	catch: (cause) => new McpTestServerError({ cause }),
213	});	178	});
214	}).pipe(	179	}).pipe(

plans/kill-plugin-system.md+515−0

@@ -0,0 +1,515 @@
	1	# Kill the plugin system — in-place migration plan
	2
	3	Decision (Rhys, 2026-07-27): abandon the big-bang rework
	4	(`UsefulSoftwareCo/executor-rework`, cloned read-only at
	5	`.reference/executor-rework`); fix this repo in place over a sequence of PRs,
	6	each keeping format/lint/typecheck/test/e2e green. Priority order: **data
	7	models first**, then the plugin kill, then the concept-package (apps) model,
	8	then the minimal SDK / platform split.
	9
	10	RESEQUENCED (Rhys, 2026-07-28): **Phase 3 (apps/concept-package model) now
	11	lands BEFORE Phase 2 (plugin kill), side by side with the protocol plugins.**
	12	Rationale: the new model's tables are greenfield and additive — landing it
	13	first means the legacy apps tables never need an in-place migration; the whole
	14	model swaps underneath while openapi/mcp/graphql keep running as plugins.
	15	Structurally sound because (a) the kernel + MCP host are already plugin-free,
	16	so the new model's runtime never touched the registry, and (b) the apps plugin
	17	already exercises every extension point, so the new model ships as the apps
	18	plugin's new internals wearing the same costume. When 2.3 later converts the
	19	four kinds, apps converts as a stable, proven model instead of mid-rewrite.
	20	Phase 0 and 2.1 remain freely parallel — they don't touch apps.
	21
	22	Hard line: side-by-side means new-apps-model alongside the _protocol plugins_,
	23	never two app models with dual read paths inside the apps kind. Existing app
	24	sources get a one-off migration to published-source form (enumerated
	25	invariants, explicit approval, no permanent compatibility path). Accepted
	26	cost: the new model's HTTP surface temporarily wears plugin-route ceremony
	27	(HttpApiGroup + handler layers) that 2.2/2.6 later deletes — wiring, not
	28	model. The authoring SDK (`defineApp`/`defineProvider`/`defineTool`) goes
	29	public early; its boundaries take Standard Schema (StandardSchemaV1 &
	30	StandardJSONSchemaV1), never Effect Schema, and Phase 4's vocabulary rules
	31	(opaque owner refs, no "tenant") bind on it from day one.
	32
	33	## Diagnosis (verified against the code)
	34
	35	The plugin system is a fiction. `packages/core/sdk/src/plugin.ts` (~850
	36	lines, ~20 optional hooks) pretends the plugin set is open, but:
	37
	38	- `Integration.kind` _is_ the plugin id string; all hot paths dispatch via
	39	`runtimes.get(row.plugin_id)` (`executor.ts`).
	40	- Core and React hardcode the closed set anyway: `migration-spec.ts` hardcodes
	41	plugin ids; `packages/react` has `KIND_TO_PLUGIN_KEY` maps and an
	42	`if (pluginId === "toolkits")` route branch.
	43	- Nobody ever shipped a fourth protocol plugin, and the two provider plugins
	44	(google/microsoft) were already collapsed into openapi (#1366).
	45	- Whole packages exist only to support the open set: `plugin-routes.ts`
	46	type-union machinery, `@executor-js/config`'s jsonc+jiti loader,
	47	`packages/core/vite-plugin`'s virtual client module. The jsonc plugin path is
	48	vestigial — no `executor.jsonc` exists anywhere in the repo, no docs mention
	49	it.
	50	- Toolkits (~880 LoC of pure curation + the single `toolPolicyProvider` slot)
	51	and apps (~6.8k custom-tools gateway) are first-party capabilities wearing a
	52	plugin costume. Kernel packages and `packages/hosts/mcp` have zero plugin
	53	references — the indirection is not load-bearing for the real surfaces.
	54
	55	The data model is connection-first, not user-first
	56	(`packages/core/sdk/src/core-schema.ts`):
	57
	58	- No user/subject table. `subject` is an opaque partition-key string smeared
	59	across owned tables; a user "exists" only if they have a connection row.
	60	- Disconnect is a hard delete (`connectionsRemove`) — a signed-out user is
	61	bit-identical to one who never connected. "Which users are signed out" is
	62	structurally unanswerable.
	63	- Every Executor is bound to one `{tenant, subject}` via `owner-policy.ts`;
	64	there is no cross-subject read path, so no admin view.
	65	- Toolkit state lives in generic `plugin_storage` KV, not core tables.
	66	- Cloud's real identity tables (WorkOS accounts/organizations) have no join to
	67	`subject`.
	68
	69	What to salvage from the rework (its model docs are the valuable artifact;
	70	its implementation ported only ~10 of 131 legacy e2e scenarios — that's why it
	71	failed, and why this plan is incremental):
	72
	73	- Apps-as-published-source: `defineApp`/`defineProvider`/`defineTool`/
	74	`defineToolGroup`, immutable content-hashed versions, manifest derived by
	75	executing the source, rollback = pointer move.
	76	- Generators: OpenAPI/MCP specs generate the _same_ app source a human would
	77	write, with a re-verifiable `GeneratorClaim` (first-party vs third-party).
	78	- Minimal SDK boundary: `createExecutor`/`createRemoteExecutor`, no Effect
	79	crossing the boundary, MCP exposure returns a standard MCP SDK server.
	80	- Custody separation: secrets never on the wire; opaque owner refs.
	81
	82	## Constraints discovered (do not relearn these)
	83
	84	1. Published packages make this semver-major. `scripts/publish-packages.ts`
	85	publishes `@executor-js/{config,sdk}` and plugins
	86	`{example,file-secrets,graphql,keychain,mcp,onepassword,openapi}` — killing
	87	`definePlugin` is a breaking release for seven packages. Changesets +
	88	deprecation story required; `publish-packages.ts`, `pkg-pr-new.yml`,
	89	`check-changelog-stubs.ts`, and `examples/*` all have hardcoded lists.
	90	2. `plugin_id = 'google'` is a live persisted value with no runtime. The
	91	provider-service-split migration skips orgs with missing spec blobs
	92	(`sqlite.test.ts` asserts survivors). The `googleDiscovery → "google"`
	93	entries in React are compensating, not dangling. The closed SourceType
	94	switch must map `"google"`/`"googleDiscovery"` → openapi or degraded rows
	95	become hard failures.
	96	3. FumaDB is not versioned in practice. All hosts pin `version: "1.0.0"`;
	97	runtime bring-up is `ensureDrizzleRuntimeSchemaFromTables` (CREATE TABLE IF
	98	NOT EXISTS + additive nullable ALTERs). New tables/nullable columns are free
	99	on local/self-host/D1. Cloud is the exception: hand-edit
	100	`apps/cloud/src/db/executor-schema.ts` + drizzle-kit migration +
	101	`db:migrate:prod`; `db.schema.test.ts` enforces the mirror, so "forgot
	102	cloud" fails tests.
	103	4. 93 e2e files import `composePluginApi` purely to type the client. Keep
	104	it as a deprecated argument-ignoring shim returning the static
	105	`FullExecutorApi`; sweep the call sites mechanically in one final PR.
	106	5. Keep the `plugin_id` column name (four tables + blob namespace format
	107	`o:<tenant>/<plugin_id>`). Renaming to `source_kind` is a cross-host
	108	migration for zero behavior. Retype on the read side only.
	109	6. URL contracts: `/integrations/add/$pluginKey` is navigated directly by
	110	e2e; `/plugins/desktop-settings/` is asserted by the desktop-packaged suite
	111	and baked into a tool's returned URL. Keep shapes / add redirects.
	112	7. CI gaps: PRs run cloud (4 shards) + selfhost e2e only; local/desktop
	113	suites gate push-to-main. PRs touching desktop-settings or the local loader
	114	need a manual local e2e run pre-merge.
	115	8. Toolkit selection filters _connections_, not just tools
	116	(`connectionsList` goes through the active policy provider). Preserve when
	117	moving toolkits to core, or the toolkit e2e suites go red.
	118
	119	## Phase 0 — declutter (3 PRs)
	120
	121	- 0.1 Delete empty `packages/plugins/{google,microsoft}`; drop the unused
	122	`@executor-js/config` dep from openapi/mcp/graphql; move
	123	`provider-service-split` to `packages/migrations/` (keep package name — it's
	124	imported by three host data-migration registries). In the React maps, keep
	125	`google`/`googleDiscovery` → openapi with a comment citing constraint 2.
	126	- 0.2 Bake google/microsoft catalogs + spec-format adapters in as openapi
	127	defaults; strip the re-threading from all four host configs. Gate:
	128	`provider-plugins-ui`, `google-health-checks`, `microsoft-*` scenarios.
	129	- 0.3 Move desktop-settings (438-line Electron-IPC client, not a
	130	one-liner) to a first-class desktop-only route in `packages/app`; update the
	131	static tool's URL and the desktop-packaged e2e selector; delete the plugin.
	132
	133	## Phase 1 — data model (4 PRs) — FIRST PRIORITY
	134
	135	Design choices (least-invasive, verified feasible):
	136
	137	- The new subject table is `tenant`-scoped, not owner-scoped — readable by
	138	any executor bound to the tenant with zero policy changes (the
	139	`integration` table already proves the pattern).
	140	- Cross-subject connection reads: add `reach: "bound" \| "tenant"` to
	141	`ExecutorOwnerPolicyContext` — widens `ownerVisibilityCondition` for reads
	142	only; `assertOwnerWritable`/`assertOwnerPatch` untouched, so admin reach can
	143	never write. Only two construction sites exist (`executor.ts`,
	144	`test-config.ts`).
	145	- Identity stays with the hosts (WorkOS / Better Auth member lists already
	146	exist behind `AccountProvider.listMembers`); the subject table is the missing
	147	join between host identity and executor connections, not a new identity
	148	system. Tolerate `subject = null` (pure-org) and `subject = "local"`.
	149
	150	PRs:
	151
	152	- 1.1 Add tenant-scoped `subject` table (id, tenant, external_id,
	153	created_at, last_seen_at, status) to `coreTables` + cloud mirror + one
	154	drizzle migration. No readers yet.
	155	- 1.2 Populate: upsert in `makeScopedExecutor`
	156	(`packages/core/api/src/server/scoped-executor.ts` — every HTTP request and
	157	MCP session on all four hosts passes through it) and at connection-create.
	158	Add to `purgeOrganizationData` + its `TENANT_TABLES` test.
	159	- 1.3 `reach` mode + `admin.listSubjectsWithConnections`-shaped read on a
	160	derived handle. Policy test proving admin reach cannot write. Scope includes
	161	(customer ask, owner.com 2026-07-27): per-subject reads ("connections for
	162	subject X"), not just the aggregate list, and a privileged org-level API key
	163	(keys already carry `{accountId, organizationId}` —
	164	`apps/cloud/src/auth/api-keys.ts`) that resolves to the tenant-reach
	165	read-only handle so customers can inspect connections programmatically.
	166	- 1.4 Connection lifecycle: nullable `status` column
	167	(active/disconnected/revoked/expired) plus `status_changed_at`; disconnect
	168	writes status instead of deleting. Wide blast radius — status predicate
	169	through `findConnectionRow`, `connectionsList`, credential resolution,
	170	`toolsList`, org purge; own e2e sweep (`connections-`, `health-checks`,
	171	`oauth-*`). PRIORITY RAISED (customer, 2026-07-28): the customer's
	172	block-startup-until-reconnect flow needs connected-then-disconnected to be
	173	distinguishable from never-connected, which hard-delete makes impossible
	174	today; expose status + statusChangedAt through the admin API when this
	175	lands.
	176
	177	Toolkits data does NOT move in this phase (it moves with its reader in 2.4 —
	178	moving it earlier means either rewriting the plugin storage layer twice or a
	179	forbidden dual read path).
	180
	181	### Framing: product view vs platform view (Rhys, 2026-07-27)
	182
	183	The two-view model for consumer-facing surfaces, longer-term:
	184
	185	- Product view — the bound, per-individual executor every request gets
	186	today (their connections, their tools). The default; unchanged.
	187	- Platform view — an operator-level view attached alongside it: read-only,
	188	cross-user, explicitly reached for with elevated access (an escape hatch,
	189	never a mode product view drifts into). The `reach: "bound" \| "tenant"`
	190	split in 1.3 is this model's first implementation; 1.5's admin API and the
	191	privileged key are its first surface. Later platform-view candidates (usage,
	192	policy overview, cross-user health) land on the same handle.
	193
	194	Cloud wrinkle: cloud consumers like owner.com don't bring their own owner ids —
	195	their users authenticate through our WorkOS, so `subject` is _our_ accountId
	196	and the customer correlates on their side. The opaque-owner-ids-in-the-
	197	customer's-id-space story fully applies only to embedded/API consumers; for
	198	cloud, the platform view (+ `external_id` on the subject table) is what makes
	199	the correlation tractable.
	200
	201	### Fast path: owner.com admin-visibility ask (ships from Phase 1 alone)
	202
	203	The owner.com ask (admin inspects users' connections; API key that can do the
	204	same; available-vs-connected icon grid; direct connect links) needs only
	205	1.1 → 1.2 → 1.3 plus a thin delivery layer — no dependency on Phase 0 or the
	206	plugin kill. Delivery PRs on top of 1.3:
	207
	208	- 1.5 Public admin API surface: `GET .../admin/users`,
	209	`GET .../admin/users/:externalId/connections` (integration slug + status +
	210	last_health only — never item_ids/oauth fields), gated on the privileged key
	211	/ admin membership. Public paths say `users`, not `subjects`/`tenants` — see
	212	"Vocabulary" below. The available-vs-connected diff is computable client-side
	213	from this plus the existing integration catalog.
	214	- 1.6 Connect deep links: stable
	215	`/connect/:integrationSlug`-shaped URL that lands the arriving user in the
	216	connect flow for that integration (auth-aware redirect). Uses integration
	217	slugs, not plugin routes, so it survives Phase 2.5 unchanged.
	218
	219	1.4 (lifecycle status) upgrades the grid from binary connected/not to
	220	expired/disconnected states but is not a blocker for first ship.
	221
	222	## Phase 2 — kill the registry (6 PRs)
	223
	224	- 2.1 Remove dynamic loading: delete `load-plugins.ts` from
	225	`@executor-js/config` (keep the rest — jsonc integration config is a separate
	226	feature), drop `loadPluginsFromJsonc` from `apps/local`, delete
	227	`packages/core/vite-plugin`, replace `virtual:executor/plugins-client` with a
	228	static module in `packages/app` (5 `__root.tsx` importers + 3 ambient
	229	`.d.ts`), edit `turbo.json` `dev.dependsOn` + root `prepare`, fix
	230	`packages/app/vite.config.ts`'s dangling jsonc path. Breaking changeset.
	231	- 2.2 Static route list: `composePluginApi` becomes the deprecated shim
	232	(constraint 4); hosts stop passing plugin tuples; delete
	233	`apps/{cloud,host-selfhost}/src/plugins.ts` (exist only to hold
	234	`PluginExtensionServices` typing).
	235	- 2.3 The switch: closed internal `SourceType` interface implemented by
	236	openapi/graphql/mcp/apps (current model, unchanged) as plain libraries,
	237	replacing `runtimes.get`. All four kinds convert together — converting three
	238	and leaving apps on the plugin path means carrying dual dispatch; rewriting
	239	the apps model in the same PR is what killed the rework. Map
	240	`"google"`/`"googleDiscovery"` → openapi. `plugin_id` column name unchanged.
	241	- 2.4 Toolkits to core: core tables + one-off migration out of
	242	`plugin_storage` (enumerated invariants, no dual path), `toolPolicyProvider`
	243	slot → native policy input (one call site, one implementation, one test),
	244	ordinary core routes, `activeToolkitSlug` becomes an executor option.
	245	Preserve the connection-visibility filter (constraint 8).
	246	- 2.5 React: four named kind renderers; move plugin React code (~2.9k LoC,
	247	e.g. `AddMcpIntegration.tsx`) into `packages/react` — watch the peer-dep
	248	edge for cycles; delete `defineClientPlugin`, the plugins context, both
	249	`KIND_TO_PLUGIN_KEY` maps, and `/plugins/$pluginId/$` (with redirects for
	250	desktop-settings + toolkits). Keep `/integrations/add/$pluginKey` URL shape.
	251	Don't forget the second axis: `useSecretProviderPlugins` (secrets page).
	252	- 2.6 Detach `CredentialProvider` from `PluginSpec` (the interface in
	253	`provider.ts` is already narrow — secret-store plugins keep it as their
	254	seam); delete `plugin.ts`, `plugin-routes.ts`, `plugin-example`, and the
	255	shim; mechanical sweep of the 93 e2e files; changesets for all seven
	256	published packages.
	257
	258	## Phase 3 — custom = concept package (3–4 PRs) — NOW BEFORE PHASE 2
	259
	260	(See RESEQUENCED note at top: lands side by side with the protocol plugins,
	261	inside the apps plugin's existing costume; Phase 2 kills the registry
	262	afterward, with apps converting in 2.3 as an already-stable model.)
	263
	264	Port the rework's app model in place as the `apps` source kind's new model:
	265	published source, manifest derived by execution, content-hashed immutable
	266	versions, rollback = pointer move. New tables are additive greenfield (same
	267	pattern as 1.1: coreTables + cloud mirror + migration, no readers first).
	268	Existing app sources migrate one-off to published-source form — no dual model
	269	within the apps kind. Then the OpenAPI/MCP generators + `GeneratorClaim` as an
	270	optional on-ramp (spec → generated app source); GraphQL generator later.
	271	Long-term option (explicitly out of scope): protocol kinds themselves become
	272	generators and "custom" is the only kind.
	273
	274	### Feasibility findings (two deep read-throughs, 2026-07-28)
	275
	276	Current plugin (~7.6k LoC): only ~2.65k encodes the old model (store
	277	collections, sync state machine, publish/discover/descriptor, routes,
	278	console client). ~2.6k is model-agnostic and survives verbatim: all three
	279	sandbox executors, the bundler stack, bindings/bridge, authoring +
	280	standard-schema, conformance. ~1.9k (hand-rolled git client + source
	281	fetchers) hangs on the publish-input decision below. Storage is entirely
	282	generic `plugin_storage` rows + content-addressed blobs — zero apps-specific
	283	tables or migrations exist, so new tables are pure greenfield. Cloud prod is
	284	git-source-only; **source text is never persisted today (only compiled
	285	bundles)**, so the one-off migration re-fetches source from the recorded git
	286	URLs (fetcher exists). Load-bearing invariants to preserve: tool addresses
	287	`tools.<app>.org.published.<name>` + the `<fileSlug>__<key>` naming rule,
	288	app-slug↔integration-slug 1:1 guard, publish CAS
	289	(`AppPublishConflictError`), tombstone-not-delete, token-in-provider-item
	290	(never in the source row). Safety net: `custom-tools.test.ts` (534-line
	291	cloud+selfhost console loop), local directory-picker, packed-CLI, desktop
	292	e2e, ~2.9k LoC in-package tests. Pre-existing gaps flagged: R2 blobs never
	293	GC'd and org purge misses them; cloud silently falls back to in-process
	294	executor without the worker loader; host-cloudflare doesn't register apps.
	295
	296	Rework model (portable tiers): T1 model proper ~3.9k LoC (authoring SDK,
	297	publish-by-execution, projection, generator verification, storage port,
	298	content hashing); T2 generators ~3.2k (fromOpenAPI 1k — complete; fromMCP
	299	0.6k — computed group with real streamable-HTTP client; json-schema engine;
	300	byte-for-byte GeneratorClaim verification; render endpoint); T4 host/registry
	301	~2.9k explicitly skipped. Authoring is Standard Schema
	302	(StandardSchemaV1 & StandardJSONSchemaV1) with raw-JSON-Schema literals as a
	303	typed first-class alternative — matches our rule. Effect beta.93→beta.59
	304	delta is small (ConstraintDecoder → one-line fix; hand-roll
	305	StandardJSONSchemaV1 ~10 lines; reuse core sha256Hex). NOT portable as-is:
	306	rework `storage-db.ts` (write a new adapter over our tables against the
	307	~90-line Storage port interface) and `engine.ts` (extract only ~700 LoC of
	308	model-owned logic: computed-surface cache + requirement resolution +
	309	runTool). Known rework gaps to fix at port time, not inherit: derive-time
	310	execution is unsandboxed in-process (`code-executor.ts:23` records it) — our
	311	port MUST run publish-time evaluation in the existing sandbox `collect` path
	312	from day one; fan-in computed groups unsupported; OAuth discovery
	313	unsupported.
	314
	315	Semantic deltas — decided by Rhys before 3.1 specs:
	316
	317	1. Handler credential contract (the deep one). Current: handlers get an
	318	opaque callable `AppIntegrationClient` proxy that re-enters
	319	`ctx.execute` — app code never sees credentials, can only call other
	320	executor tools. Rework (D49): engine resolves credentials once and hands
	321	the handler credential fields as data (`ResolvedConnection.fields`,
	322	e.g. access_token) for direct HTTP — that's what makes generators
	323	possible (generated code does raw fetch with auth) and what
	324	`defineProvider` exists for. Not either/or in principle (a tool-call
	325	bridge can coexist as a second requirement kind later), but the ported
	326	model's primary contract is fields-as-data per the rework.
	327	2. Publish input. Rework publish takes `SourceFiles` (push-based).
	328	Decision: keep git/local-directory as _fetchers that produce
	329	SourceFiles_ (preserves prod sources, the e2e suite, and the migration
	330	path; git-client survives), with direct push publish added as the new
	331	API. Delete-git-later stays open.
	332	3. App identity moves from caller-supplied slug to the `defineApp`
	333	export inside the source (rework shape).
	334	4. Versioning: content hash of source IS the version identity; the
	335	caller-supplied `sourceRef` + descriptor v6 die with the old model.
	336	5. Ownership: app/version rows carry `space` and NO owner — spaces
	337	curate apps, principals own custody (connections stay on the legacy
	338	owner model in this phase; the opaque-OwnerRef swap is Phase 4).
	339
	340	### Phase 3 PR sequence (revised)
	341
	342	- 3.1 Port the model core as internal packages, no readers: authoring
	343	SDK + runtime brands, publish pipeline (evaluation routed through the
	344	sandbox `collect` seam), Storage port + adapter, greenfield tables
	345	(`app`, `app_version`, `computed_surface` — space column, content-hash
	346	identity, `current` pointer) in coreTables + cloud mirror + migration.
	347	Ported rework tests come along (authoring-boundary, tool-groups,
	348	publish).
	349	- 3.2 Swap the apps plugin's internals onto the new model behind the
	350	same costume: resolveTools/projectToolSchema/invokeTool read the new
	351	tables; publish endpoint (`POST` source files); setCurrent/rollback +
	352	versions listing routes; git/local-dir sync becomes fetch→publish.
	353	Tool addresses and slug guards preserved; old collections
	354	(`apps_descriptors`/`apps_tools`/`apps_sources`) still written by
	355	NOTHING — one-off migration converts existing sources (re-fetch from
	356	git), then the collections are dead. e2e: full existing custom-tools
	357	suite green + new version-history/rollback scenario.
	358	- 3.3 Console UI for the new model (sources → apps with versions,
	359	publish status, rollback) replacing the ~1.3k LoC old client/panels.
	360	- 3.4 Generators: fromOpenAPI + fromMCP + GeneratorClaim verification +
	361	render endpoint, surfaced as the "add from spec/server" on-ramp.
	362	(Vendors google/microsoft conversion ~1.15k LoC ports later with 0.2.)
	363
	364	## Spaces: the rework's tenancy primitive (added Rhys, 2026-07-28)
	365
	366	The rework's SDK has exactly one tenancy concept: `SpaceId`
	367	(`.reference/executor-rework/docs/TENANCY.md`, `docs/MODEL.md`). Adopt it as
	368	the end-state tenancy model here. The shape:
	369
	370	- Flat, no hierarchy, no default. No parent, no inheritance, no
	371	distinguished rows (rework D39/D44b). Sharing is an explicit act, never a
	372	tree walk (R2 — re-ruled twice, do not relitigate). Every scoped row
	373	carries a `space` column; every space-scoped route carries the space in
	374	the URL path, never ambient context.
	375	- No org/project/team/user below the deployment edge. The engine answers
	376	"what is in this space"; the deployment answers "who is this and which
	377	spaces may they touch" through named seams (`authorizeBrowserResource`,
	378	`dashboardSpacesForPrincipal`, MCP space resolver). Membership is
	379	authorized LIVE per request at the edge — projection may be cached,
	380	authorization never.
	381	- Deployment mappings: cloud = one WorkOS org mirrors lazily to one
	382	space (mirror row `workosOrgId → space` is also the billing join — Autumn
	383	keys on workosOrgId, never a space); self-host = one instance, one
	384	found-or-created "Default" space, Better Auth org repurposed as the
	385	instance membership table; local/desktop = one "local" space, one static
	386	principal, single-tenancy declared via explicit sentinel, not defaulted.
	387	- Spaces curate, principals own. Custody (secrets, connections'
	388	secret-bearing halves) belongs to principals via opaque `OwnerRef` +
	389	per-request `Reach` (R3); spaces curate apps and hold rows. Publishing an
	390	app into a space IS its presence there — no installation rows, no
	391	bindings; cross-space arrival (sharing/registry) is a future share-edge
	392	row, not golden-path ceremony (D45/D42).
	393	- Cross-org OAuth callbacks complete into the _initiating_ org's space; the
	394	org header is a routing hint, not an authorization statement (R7).
	395
	396	**DECIDED (Rhys, 2026-07-28): spaces land in the CORE PRODUCT NOW — Phase S,
	397	before the apps port.** Apps then publishes into real spaces from birth.
	398
	399	Mapping onto this repo — the no-migration trick: today's `tenant` column
	400	is de facto the space — cloud writes the WorkOS org id there, self-host/local
	401	write one constant. So: keep the persisted `tenant` column name (same rule as
	402	`plugin_id`), and declare that its value IS the space id. Each org's
	403	first space is grandfathered with `spaceId = <historical tenant value>` (the
	404	org id); NEW spaces mint fresh ids written into the same column. The org→
	405	space mirror table records which space ids belong to which org (and carries
	406	the billing join — Autumn keys on workosOrgId, never a space). Existing rows
	407	never move; multi-space needs no schema change on scoped tables. "Space" is
	408	contract vocabulary; "tenant" retreats to cloud-internal (see Vocabulary).
	409
	410	### Phase S — spaces in core (before apps)
	411
	412	- S1 — space table + boot ensure (no readers). Greenfield `space` table
	413	(id, name, created_at) in coreTables + cloud mirror + migration, plus the
	414	cloud `org→space` mirror table. Boot/first-contact ensures the degenerate
	415	space per deployment: cloud lazily on first authenticated org contact
	416	(grandfathered id = org id), self-host "Default", local "local". Same
	417	no-readers pattern as PR 1.1.
	418	- S2 — space threading. `SpaceId` brand in the SDK; the scoped-executor
	419	seam resolves request → space id (today: identical to tenant) and stamps
	420	it; reads interpret `tenant` columns as space ids. No behavior change —
	421	this is the retype + vocabulary PR. `reach: "tenant"` reads as
	422	"space-wide reach" from here on.
	423	- S3 — multi-space on cloud + product surface. Create/rename space,
	424	space switcher in the console, membership = org membership (all spaces of
	425	the org for now), org→N mirror rows, space-scoped catalog/connection
	426	views (rows follow automatically — they're keyed by the space id in the
	427	tenant column). Billing stays org-keyed via the mirror. e2e: two spaces
	428	in one org, isolation of catalogs/connections between them, switcher.
	429	- S4 — sharing model on spaces. Connect-time "share with space" writes
	430	the space's shared owner-ref (replaces the org tier semantically; the
	431	persisted `owner: "org"\|"user"` column keeps its name, read-side
	432	reinterpretation only). Edge computes reach as
	433	[principal, sharedRef(space) for each member space]. This is the bridge
	434	to Phase 4's full owner-set reach.
	435	- Later (not scheduled): local multi-space, file-backed. Each local
	436	space is its own store file (portable — copy/backup/sync/check in
	437	alongside a repo); the daemon opens one storage handle per space and
	438	routes by space id; the engine still sees flat SpaceIds. Custody never
	439	enters the space file — secrets stay in the principal-keyed provider
	440	(keychain), so a copied file carries connection metadata, never tokens.
	441	- Phase 4 completes the picture: space-in-path routes,
	442	`dashboardSpacesForPrincipal`-style seams, reach as an explicit owner
	443	set.
	444
	445	Apps (Phase 3) then lands after S1/S2 — app rows carry a real `space` FK
	446	from birth; S3/S4 can proceed in parallel with the apps port.
	447
	448	Interaction with shipped Phase 1 work: the subject table and platform view
	449	are edge/deployment concepts (who exists in this identity world, what may
	450	an operator read) — they sit above spaces and survive unchanged; `reach:
	451	"tenant"` becomes "space-wide reach" vocabulary-wise at Phase 4.
	452
	453	## Vocabulary: retire "tenant" from consumer-facing surfaces (Rhys, 2026-07-27)
	454
	455	Direction: the SDK should be agnostic to the consumer's data-model shape, the
	456	way Composio's is — consumers pass an opaque user/owner id string and hang
	457	whatever hierarchy they have (user, team, workspace) off it; the SDK never
	458	models their org chart. The rework already designed this (`OwnerRef` opaque
	459	brand, `Reach = {owners}`, deployments translate identity at the edge) — adopt
	460	its vocabulary, not its schedule. "Tenant" remains a real _internal_ concept
	461	(which Executor-cloud org owns the rows) but must not leak into surfaces
	462	consumers touch.
	463
	464	Rules, effective immediately:
	465
	466	- Persisted column names (`tenant`, `subject`, `owner`) stay — renaming
	467	storage is a cross-host migration for zero behavior (same rule as
	468	`plugin_id`).
	469	- Internal policy code (`reach: "tenant"`, `ExecutorOwnerPolicyContext`) may
	470	keep the words.
	471	- One contract noun: `owner` — the opaque ref naming who a connection
	472	belongs to (end-user, team, workspace, or the org itself; the rework's
	473	`OwnerRef`). "User" cannot be the contract noun because org-shared
	474	connections are a load-bearing feature an end-user word can't cover.
	475	- "user" is presentation vocabulary only, for surfaces whose rows genuinely
	476	are the customer's end-users — the Phase 1.5 admin API says `users` because
	477	the subject table is populated from authenticated principals.
	478	- Hazard: the persisted `owner` column keeps its old meaning (the
	479	`"org" \| "user"` tier discriminator), while Phase 4 introduces the opaque
	480	ref as a distinctly named type (`OwnerRef`). Same word, two meanings,
	481	separated by layer — say so in policy-layer comments.
	482	- The full swap (opaque owner refs at the SDK boundary, tenant retreating to a
	483	cloud-internal detail) lands with the Phase 4 minimal SDK.
	484
	485	## Phase 4 — minimal SDK + platform/product split
	486
	487	New consumer boundary modeled on the rework: `createExecutor` /
	488	`createRemoteExecutor`, no Effect at the boundary, `tools.list/execute` +
	489	connections + the new users/admin surface; policies/toolkits become optional
	490	layers consumers opt into, not baked opinions (Composio-style minimalism).
	491
	492	Authorization end-state (Rhys, 2026-07-27): the engine enforces scope
	493	mechanically but never decides policy — the host computes, per request, the
	494	set of owners the request may read (the rework's `Reach = { owners }`), and
	495	the storage predicate is just `row.owner ∈ reach.owners`. The 1.3
	496	`reach: "bound" \| "tenant"` enum is a stepping stone and is replaced by this
	497	set shape here: "bound" = a reach of one, "tenant" = all owners (wildcard so
	498	cloud needn't enumerate), and in-between cases (team views, support sessions,
	499	subset-restricted org keys) are just different sets. Writes stay hard-pinned
	500	to a single owner; only read reach generalizes. Trust model becomes a
	501	per-deployment choice: a trusted backend with a server key gets tenant-wide
	502	reach and layers its own authorization (Composio-style); an end-user session
	503	gets a reach of one. The enum-to-set swap is contained: the policy context is
	504	constructed in exactly two places.
	505	Start the platform/product package separation _during_ 2.3–2.6 (each PR moves
	506	one thing to its final home) rather than as a big bang; the SDK boundary
	507	itself lands last.
	508
	509	## Bookkeeping
	510
	511	- Create `MISTAKES.md` / `DESIRES.md` / `LEARNINGS.md` (required by AGENTS.md,
	512	currently missing) with the first entries from this migration.
	513	- `apps/local/src/db/executor-schema.ts` is already stale vs `coreTables`
	514	(missing several columns); its "keep in sync" comment is untrustworthy —
	515	runtime schema comes from the ensure path, not this file.