fix(workspace): guard connect/disconnect; keep the engine through a transient fault

The SDK and HTTP connect/disconnect routes refuse the workspace-managed key
before `MCP` would restart or close it and persist `enabled`. The add guard
runs before the API lookup; create/remove preflights sit inside their error
boundaries. A managed-preferences key settles as disabled with no per-turn
reload; an overlay that throws after attach keeps the running engine. The
headless env scrub is tested.

Author: ralphstodomingo

packages/opencode/src/altimate/tools/datamate.ts

@@ -191,11 +191,30 @@ async function handleAdd(args: { datamate_id?: string; name?: string; scope?: "p
     }
   }
   try {
-    const datamate = await AltimateApi.getDatamate(args.datamate_id)
     // readDatamateTransportFromIde returns the exact command from the IDE config so we
     // reuse the same process the extension already manages, not a second one.
     const transport = await readDatamateTransportFromIde(projectRoot())
 
+    // altimate_change start — in workspace mode the shared `datamate` key is the
+    // bound workspace's own engine, derived at config load. With an IDE transport
+    // the add would go under that key; refuse and say why, before anything is
+    // looked up — the refusal must not depend on the API being reachable.
+    // Standalone `datamate-<name>` entries are a different key and stay the user's.
+    const managed = transport !== null ? await managedWorkspaceLoaded() : null
+    if (managed) {
+      return {
+        title: `Datamate add: '${DATAMATE_KEY}' is managed by workspace "${managed.name}"`,
+        metadata: { serverName: DATAMATE_KEY, managedBy: managed.id, datamateId: args.datamate_id },
+        output:
+          `This project is linked to workspace "${managed.name}", whose integrations are served by the ` +
+          `workspace's own engine under the '${DATAMATE_KEY}' MCP server. Adding datamate '${args.datamate_id}' ` +
+          `there is not applied. Unlink the project, or run without ALTIMATE_WORKSPACE, to manage that entry by hand.`,
+      }
+    }
+    // altimate_change end
+
+    const datamate = await AltimateApi.getDatamate(args.datamate_id)
+
     if (transport !== null) {
       log.info("handleAdd: IDE transport detected, entering single-gateway mode", {
         serverName: DATAMATE_KEY,
@@ -216,23 +235,6 @@ async function handleAdd(args: { datamate_id?: string; name?: string; scope?: "p
       ? DATAMATE_KEY
       : (args.name ?? `datamate-${slugify(datamate.name)}`)
 
-    // altimate_change start — in workspace mode the shared `datamate` key is the
-    // bound workspace's own engine, derived at config load. Adding a datamate
-    // under that key would replace it; refuse and say why. Standalone
-    // `datamate-<name>` entries are a different key and stay the user's.
-    const managed = serverName === DATAMATE_KEY ? await managedWorkspaceLoaded() : null
-    if (managed) {
-      return {
-        title: `Datamate add: '${DATAMATE_KEY}' is managed by workspace "${managed.name}"`,
-        metadata: { serverName: DATAMATE_KEY, managedBy: managed.id, datamateId: args.datamate_id },
-        output:
-          `This project is linked to workspace "${managed.name}", whose integrations are served by the ` +
-          `workspace's own engine under the '${DATAMATE_KEY}' MCP server. Adding datamate '${datamate.name}' ` +
-          `there is not applied. Unlink the project, or run without ALTIMATE_WORKSPACE, to manage that entry by hand.`,
-      }
-    }
-    // altimate_change end
-
     const creds = transport ? undefined : await AltimateApi.getCredentials()
     const mcpConfig =
       transport?.type === "remote"
@@ -356,24 +358,24 @@ async function handleCreate(args: {
       output: "Missing required parameter 'name'.",
     }
   }
-  // altimate_change start — with an IDE transport the add that follows would go
-  // under the shared `datamate` key; in workspace mode that add is refused, so
-  // refuse here before creating an API datamate nothing would connect to.
-  if ((await readDatamateTransportFromIde(projectRoot())) !== null) {
-    const managedKey = await managedWorkspaceLoaded()
-    if (managedKey) {
-      return {
-        title: `Datamate create: '${DATAMATE_KEY}' is managed by workspace "${managedKey.name}"`,
-        metadata: { serverName: DATAMATE_KEY, managedBy: managedKey.id },
-        output:
-          `This project is linked to workspace "${managedKey.name}", whose integrations are served by the ` +
-          `workspace's own engine under the '${DATAMATE_KEY}' MCP server. Creating datamate '${args.name}' ` +
-          `here would not connect it. Unlink the project, or run without ALTIMATE_WORKSPACE, first.`,
+  try {
+    // altimate_change start — with an IDE transport the add that follows would go
+    // under the shared `datamate` key; in workspace mode that add is refused, so
+    // refuse here before creating an API datamate nothing would connect to.
+    if ((await readDatamateTransportFromIde(projectRoot())) !== null) {
+      const managedKey = await managedWorkspaceLoaded()
+      if (managedKey) {
+        return {
+          title: `Datamate create: '${DATAMATE_KEY}' is managed by workspace "${managedKey.name}"`,
+          metadata: { serverName: DATAMATE_KEY, managedBy: managedKey.id },
+          output:
+            `This project is linked to workspace "${managedKey.name}", whose integrations are served by the ` +
+            `workspace's own engine under the '${DATAMATE_KEY}' MCP server. Creating datamate '${args.name}' ` +
+            `here would not connect it. Unlink the project, or run without ALTIMATE_WORKSPACE, first.`,
+        }
       }
     }
-  }
-  // altimate_change end
-  try {
+    // altimate_change end
     const integrations = args.integration_ids
       ? await AltimateApi.resolveIntegrations(args.integration_ids)
       : undefined
@@ -535,23 +537,23 @@ async function handleRemove(args: { server_name?: string; scope?: "project" | "g
         "Missing required parameter 'server_name'. Use 'status' to see active servers or 'list-config' to see saved configs.",
     }
   }
-  // altimate_change start — the workspace-managed `datamate` key is not the
-  // user's to remove either: it would stop the engine under a turn and delete
-  // the entry that unlinking hands back. Standalone `datamate-<name>` entries
-  // are unaffected.
-  const managedKey = args.server_name === DATAMATE_KEY ? await managedWorkspaceLoaded() : null
-  if (managedKey) {
-    return {
-      title: `Datamate remove: '${DATAMATE_KEY}' is managed by workspace "${managedKey.name}"`,
-      metadata: { serverName: DATAMATE_KEY, managedBy: managedKey.id },
-      output:
-        `This project is linked to workspace "${managedKey.name}", whose integrations are served by the ` +
-        `workspace's own engine under the '${DATAMATE_KEY}' MCP server. It is not removed. Unlink the project, ` +
-        `or run without ALTIMATE_WORKSPACE, to manage that entry by hand.`,
-    }
-  }
-  // altimate_change end
   try {
+    // altimate_change start — the workspace-managed `datamate` key is not the
+    // user's to remove either: it would stop the engine under a turn and delete
+    // the entry that unlinking hands back. Standalone `datamate-<name>` entries
+    // are unaffected.
+    const managedKey = args.server_name === DATAMATE_KEY ? await managedWorkspaceLoaded() : null
+    if (managedKey) {
+      return {
+        title: `Datamate remove: '${DATAMATE_KEY}' is managed by workspace "${managedKey.name}"`,
+        metadata: { serverName: DATAMATE_KEY, managedBy: managedKey.id },
+        output:
+          `This project is linked to workspace "${managedKey.name}", whose integrations are served by the ` +
+          `workspace's own engine under the '${DATAMATE_KEY}' MCP server. It is not removed. Unlink the project, ` +
+          `or run without ALTIMATE_WORKSPACE, to manage that entry by hand.`,
+      }
+    }
+    // altimate_change end
     // Fully remove from runtime state (disconnect + purge from MCP list)
     // altimate_change start — MCP.remove (was disconnect): delete the status entry + publish
     // ToolsChanged so the removed server's tools stop being offered without a restart.

packages/opencode/src/altimate/workspace/engine-overlay.ts

@@ -124,6 +124,8 @@ type DirectoryState = {
   /** When the last overlay attempt threw. A failed attempt is retried at the
    * probe TTL, not on every turn — each retry invalidates the whole config. */
   failedAt?: number
+  /** The key is set by organisation-managed config: nothing here claims it. */
+  managed?: boolean
 }
 const directories = new Map<string, DirectoryState>()
 
@@ -152,6 +154,7 @@ export async function overlay(
 ): Promise<void> {
   const state = stateFor(directory)
   state.failedAt = undefined
+  state.managed = opts.managed === true
   try {
     if (!isEnabled() || isServe()) {
       state.current = null
@@ -362,6 +365,15 @@ async function reconcile(sessionID: string, directory: string, state: DirectoryS
   // the overlay as it stands now.
   if (state.applied === undefined) state.applied = state.current
 
+  // Organisation-managed config owns the key: the feature is off for this
+  // directory, whatever the binding says. Nothing to reload per turn.
+  if (state.managed) {
+    if (state.applied?.entry) await releaseKey(await config().get(), true)
+    state.applied = null
+    record(sessionID, { kind: "disabled" })
+    return
+  }
+
   const binding = await resolveBinding(directory)
   if (!binding) {
     // Unlinked (or never linked): the key is not ours to fill.
@@ -394,7 +406,9 @@ async function reconcile(sessionID: string, directory: string, state: DirectoryS
     loaded = await config().get()
   }
 
-  const overlayNow = state.current
+  // A transient overlay failure (its retry is throttled above) keeps what was
+  // last applied: a running engine is not released over a fault in the probe.
+  const overlayNow = state.current ?? (state.failedAt !== undefined ? (state.applied ?? null) : null)
   if (!overlayNow) {
     if (state.applied) await releaseKey(loaded, !!state.applied.entry)
     state.applied = null

packages/opencode/src/server/routes/instance/httpapi/groups/mcp.ts

@@ -127,7 +127,9 @@ export const McpApi = HttpApi.make("mcp")
           params: { name: Schema.String },
           query: WorkspaceRoutingQuery,
           success: described(Schema.Boolean, "MCP server connected successfully"),
-          error: McpServerNotFoundError,
+          // altimate_change start — the workspace-managed key refuses connect/disconnect
+          error: [McpServerNotFoundError, McpServerManagedError],
+          // altimate_change end
         }).annotateMerge(
           OpenApi.annotations({
             identifier: "mcp.connect",
@@ -138,7 +140,9 @@ export const McpApi = HttpApi.make("mcp")
           params: { name: Schema.String },
           query: WorkspaceRoutingQuery,
           success: described(Schema.Boolean, "MCP server disconnected successfully"),
-          error: McpServerNotFoundError,
+          // altimate_change start — the workspace-managed key refuses connect/disconnect
+          error: [McpServerNotFoundError, McpServerManagedError],
+          // altimate_change end
         }).annotateMerge(
           OpenApi.annotations({
             identifier: "mcp.disconnect",

packages/opencode/src/server/routes/instance/httpapi/handlers/mcp.ts

@@ -101,7 +101,28 @@ export const mcpHandlers = HttpApiBuilder.group(InstanceHttpApi, "mcp", (handler
       return { success: true as const }
     })
 
+    // altimate_change start — connect/disconnect persist `enabled` for the key and
+    // restart or close its client: neither may touch the workspace-managed
+    // `datamate`, which is derived per process and never written to a file.
+    const refuseManaged = Effect.fn("McpHttpApi.refuseManaged")(function* (name: string) {
+      if (name !== DATAMATE_KEY) return
+      yield* configSvc.get()
+      const managed = managedWorkspace(yield* InstanceState.directory)
+      if (!managed) return
+      yield* Effect.logWarning("mcp connect/disconnect refused: key is managed by a workspace", {
+        name: DATAMATE_KEY,
+        workspace: managed.id,
+      })
+      return yield* new McpServerManagedError({
+        error: `MCP server "${DATAMATE_KEY}" is managed by workspace "${managed.name}" in this project`,
+      })
+    })
+    // altimate_change end
+
     const connect = Effect.fn("McpHttpApi.connect")(function* (ctx: { params: { name: string } }) {
+      // altimate_change start
+      yield* refuseManaged(ctx.params.name)
+      // altimate_change end
       yield* mcp
         .connect(ctx.params.name)
         .pipe(
@@ -115,6 +136,9 @@ export const mcpHandlers = HttpApiBuilder.group(InstanceHttpApi, "mcp", (handler
     })
 
     const disconnect = Effect.fn("McpHttpApi.disconnect")(function* (ctx: { params: { name: string } }) {
+      // altimate_change start
+      yield* refuseManaged(ctx.params.name)
+      // altimate_change end
       yield* mcp
         .disconnect(ctx.params.name)
         .pipe(

packages/opencode/src/server/routes/mcp.ts

@@ -215,6 +215,15 @@ export const McpRoutes = lazy(() =>
       validator("param", z.object({ name: z.string() })),
       async (c) => {
         const { name } = c.req.valid("param")
+        // altimate_change start — the workspace-managed key is not restarted or persisted from here
+        const managed = name === DATAMATE_KEY ? await managedWorkspaceLoaded() : null
+        if (managed) {
+          return c.json(
+            { error: `MCP server "${name}" is managed by workspace "${managed.name}" in this project` },
+            409,
+          )
+        }
+        // altimate_change end
         await MCP.connect(name)
         return c.json(true)
       },
@@ -238,6 +247,15 @@ export const McpRoutes = lazy(() =>
       validator("param", z.object({ name: z.string() })),
       async (c) => {
         const { name } = c.req.valid("param")
+        // altimate_change start — the workspace-managed key is not closed or persisted from here
+        const managed = name === DATAMATE_KEY ? await managedWorkspaceLoaded() : null
+        if (managed) {
+          return c.json(
+            { error: `MCP server "${name}" is managed by workspace "${managed.name}" in this project` },
+            409,
+          )
+        }
+        // altimate_change end
         await MCP.disconnect(name)
         return c.json(true)
       },

packages/opencode/test/altimate/workspace/engine-overlay.test.ts

@@ -70,6 +70,7 @@ function install(opts: {
   tools?: Record<string, unknown>
   mcp?: Record<string, unknown>
   noMcpKey?: boolean
+  managed?: boolean
 }): Harness {
   const h: Harness = {
     config: opts.noMcpKey ? {} : { mcp: opts.mcp ?? {} },
@@ -138,7 +139,7 @@ function install(opts: {
       h.gets += 1
       if (loaded) return h.config
       h.config = opts.noMcpKey ? {} : { mcp: structuredClone(initialMcp ?? {}) }
-      await overlay(DIR, h.config)
+      await overlay(DIR, h.config, { managed: opts.managed === true })
       // MCP bootstraps from the config as first loaded — after the overlay had
       // its say — and keeps whatever client that started until told otherwise.
       if (h.live === undefined) h.live = DATAMATE_KEY in (h.config.mcp ?? {})
@@ -492,11 +493,42 @@ describe("beforeTurn — what a turn boundary does", () => {
   })
 
   test("a datamate key set by managed preferences is left alone and is not managed here", async () => {
-    const h = install({ mcp: { datamate: IDE_ENTRY } })
-    await overlay(DIR, h.config, { managed: true })
+    const h = install({ mcp: { datamate: IDE_ENTRY }, managed: true })
+    await beforeTurn("s1")
+    await beforeTurn("s1")
     expect(h.config.mcp).toEqual({ datamate: IDE_ENTRY })
     expect(managedWorkspace()).toBeNull()
     expect(h.probes).toBe(0)
+    // The feature is off here: no per-turn reload, no toast, nothing removed.
+    expect(h.invalidates).toBe(0)
+    expect(h.removes).toBe(0)
+    expect(h.toasts).toEqual([])
+    expect(settledOutcome("s1")).toEqual({ kind: "disabled" })
+  })
+
+  test("a transient overlay failure after attach keeps the running engine", async () => {
+    const h = install({})
+    // MCP bootstrapped the engine from the config as loaded; the hook adds nothing.
+    await beforeTurn("s1")
+    expect(h.added).toHaveLength(0)
+    expect(settledOutcome("s1")?.kind).toBe("attached")
+    // Something else invalidates config, and the overlay's probe now throws.
+    syncInternals.which = () => {
+      throw new Error("PATH unreadable")
+    }
+    await syncInternals.config!.invalidate()
+    await beforeTurn("s1")
+    expect(h.removes).toBe(0)
+    expect(h.added).toHaveLength(0)
+    expect(settledOutcome("s1")?.kind).toBe("attached")
+    // The fault clears and the TTL passes: still the same engine, not a second one.
+    h.which = "/usr/local/bin/datamate"
+    syncInternals.which = () => h.which
+    h.clock += FAILED_PROBE_TTL_MS
+    await beforeTurn("s1")
+    expect(h.added).toHaveLength(0)
+    expect(h.removes).toBe(0)
+    expect(settledOutcome("s1")?.kind).toBe("attached")
   })
 
   test("an unlink hands the key back to the entry the reloaded config restores", async () => {