fix(mcp): bind lifecycle operations to sandbox target

src/lib/actions/sandbox/mcp-bridge-adapter-hermes-branding.test.ts

@@ -3,7 +3,10 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import type { McpBridgeEntry } from "../../state/registry";
+
 const mocks = vi.hoisted(() => ({
+  getSandboxOrThrow: vi.fn(),
   isShieldsDown: vi.fn(),
   runOpenshellProviderCommand: vi.fn(),
 }));
@@ -16,11 +19,35 @@ vi.mock("../../shields", () => ({
   isShieldsDown: mocks.isShieldsDown,
 }));
 
-import { assertHermesMcpMutationRuntimeCapability } from "./mcp-bridge-adapter-hermes";
+vi.mock("./mcp-bridge-state", () => ({
+  getSandboxOrThrow: mocks.getSandboxOrThrow,
+}));
+
+import {
+  assertHermesMcpMutationRuntimeCapability,
+  unregisterHermesAdapter,
+} from "./mcp-bridge-adapter-hermes";
+
+const entry: McpBridgeEntry = {
+  server: "github",
+  agent: "hermes",
+  adapter: "hermes-config",
+  url: "https://api.githubcopilot.com/mcp/",
+  env: ["GITHUB_TOKEN"],
+  providerName: "alpha-mcp-github",
+  providerId: "11111111-2222-4333-8444-555555555555",
+  policyName: "mcp-bridge-github",
+  addedAt: new Date(0).toISOString(),
+};
 
 describe("Hermes MCP recovery guidance", () => {
   beforeEach(() => {
     vi.stubEnv("NEMOCLAW_INVOKED_AS", "nemohermes");
+    mocks.getSandboxOrThrow.mockReset().mockReturnValue({
+      agent: "hermes",
+      gatewayName: "nemoclaw-8091",
+      name: "alpha",
+    });
     mocks.isShieldsDown.mockReset().mockReturnValue(true);
     mocks.runOpenshellProviderCommand.mockReset().mockReturnValue({
       status: 1,
@@ -38,4 +65,26 @@ describe("Hermes MCP recovery guidance", () => {
       "Run `nemohermes alpha recover` and retry.",
     );
   });
+
+  it("pins Hermes MCP lifecycle commands to the recorded runtime target (#10514)", () => {
+    vi.stubEnv("OPENSHELL_GATEWAY", "ambient-gateway");
+    vi.stubEnv("OPENSHELL_GATEWAY_ENDPOINT", "https://ambient.invalid");
+    vi.stubEnv("OPENSHELL_GATEWAY_INSECURE", "true");
+    vi.stubEnv("OPENSHELL_WORKSPACE", "ambient-workspace");
+    mocks.runOpenshellProviderCommand.mockImplementation((_args, options) => {
+      expect(options?.runtimeSelection).toEqual({
+        gatewayName: "nemoclaw-8091",
+        workspace: "default",
+      });
+      return {
+        status: 0,
+        stdout: JSON.stringify({ changed: true, ok: true, reloaded: true }),
+        stderr: "",
+      };
+    });
+
+    expect(() => assertHermesMcpMutationRuntimeCapability("alpha")).not.toThrow();
+    expect(() => unregisterHermesAdapter("alpha", entry)).not.toThrow();
+    expect(mocks.runOpenshellProviderCommand).toHaveBeenCalledTimes(2);
+  });
 });

src/lib/actions/sandbox/mcp-bridge-adapter-hermes.ts

@@ -22,7 +22,9 @@ import {
 } from "./mcp-bridge-adapter-status";
 import { McpBridgeError } from "./mcp-bridge-contracts";
 import { commandOutput, redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
+import { getMcpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
+import { getSandboxOrThrow } from "./mcp-bridge-state";
 import { executeGatewaySupervisorAction } from "./process-recovery";
 
 const HERMES_MCP_EXEC_TIMEOUT_SECONDS = 620;
@@ -121,6 +123,7 @@ export function assertHermesMcpConfigMutationAllowed(sandboxName: string): void
  */
 export function assertHermesMcpMutationRuntimeCapability(sandboxName: string): void {
   assertHermesMcpConfigMutationAllowed(sandboxName);
+  const runtimeSelection = getMcpProviderInspectionRuntimeSelection(getSandboxOrThrow(sandboxName));
   let lastDetail = "";
   const probe = (): boolean => {
     let result: ReturnType<typeof runOpenshellProviderCommand>;
@@ -133,6 +136,7 @@ export function assertHermesMcpMutationRuntimeCapability(sandboxName: string): v
         ),
         {
           ignoreError: true,
+          runtimeSelection,
           stdio: ["ignore", "pipe", "pipe"],
           timeout: 45_000,
         },
@@ -232,8 +236,12 @@ function runHermesAdapterCommand(
   // placeholder and endpoint metadata.
   let result: ReturnType<typeof runOpenshellProviderCommand>;
   try {
+    const runtimeSelection = getMcpProviderInspectionRuntimeSelection(
+      getSandboxOrThrow(sandboxName),
+    );
     result = runOpenshellProviderCommand(buildHermesMcpExecArgs(sandboxName, command), {
       ignoreError: true,
+      runtimeSelection,
       stdio: ["ignore", "pipe", "pipe"],
       // The remote supervisor enforces 620s; keep a small transport margin so
       // remote termination is observed before this local subprocess is killed.

src/lib/actions/sandbox/mcp-bridge-adapter-registration.test.ts

@@ -70,6 +70,7 @@ const lifecycleSuccess = {
 const commandSuccess = { status: 0, stdout: "", stderr: "" };
 const registered = { status: 0, stdout: "registered\n", stderr: "" };
 const mismatch = { status: 0, stdout: "mismatch\n", stderr: "" };
+const sandbox = { name: "alpha", agent: "hermes", gatewayName: "nemoclaw-8091" };
 
 interface AdapterCase {
   name: string;
@@ -164,6 +165,7 @@ describe.each(adapterCases)("$name MCP adapter registration", (adapterCase) => {
     mocks.executeGatewaySupervisorAction.mockReset();
     mocks.runOpenshellProviderCommand.mockReset();
     mocks.getSandbox.mockReset();
+    mocks.getSandbox.mockReturnValue(sandbox);
   });
 
   it("re-reads the persisted definition before registration succeeds", () => {
@@ -269,6 +271,7 @@ describe("Hermes MCP adapter credential revision", () => {
     mocks.executeSandboxCommand.mockReset();
     mocks.runOpenshellProviderCommand.mockReset();
     mocks.getSandbox.mockReset();
+    mocks.getSandbox.mockReturnValue(sandbox);
   });
 
   it("writes and verifies the readiness-proven revision", () => {
@@ -302,6 +305,7 @@ describe.each(reconciliationCases)("$name MCP credential revision reconciliation
     mocks.executeSandboxCommand.mockReset();
     mocks.runOpenshellProviderCommand.mockReset();
     mocks.getSandbox.mockReset();
+    mocks.getSandbox.mockReturnValue(sandbox);
     mocks.observeMcpCredentialRevision.mockReset();
     mocks.observeMcpCredentialRevision.mockReturnValue("v12");
   });

src/lib/actions/sandbox/mcp-bridge-adapter-teardown.test.ts

@@ -14,6 +14,7 @@ const mocks = vi.hoisted(() => ({
   getSandboxAgent: vi.fn(),
   getSandboxPolicy: vi.fn(),
   getSandboxOrThrow: vi.fn(),
+  inspectExactMcpDestroyProvider: vi.fn(),
   inspectMcpProvider: vi.fn(),
   observeMcpCredentialRevision: vi.fn(),
   removeGeneratedPolicy: vi.fn(),
@@ -42,6 +43,10 @@ vi.mock("./mcp-bridge-provider", () => ({
   assertNoProviderCredentialCollisions: vi.fn(),
   assertNoRegisteredProviderCredentialCollisions: vi.fn(),
   detachProvider: vi.fn(),
+  getMcpProviderInspectionRuntimeSelection: vi.fn(() => ({
+    gatewayName: "nemoclaw-8091",
+    workspace: "default",
+  })),
   inspectMcpProvider: mocks.inspectMcpProvider,
   preflightMcpEntryTargets: vi.fn(),
   waitForDetachedMcpCredential: vi.fn(),
@@ -50,7 +55,7 @@ vi.mock("./mcp-bridge-provider", () => ({
 vi.mock("./mcp-bridge-destroy-preflight", () => ({
   cloneMcpBridgeEntry: vi.fn((entry: McpBridgeEntry) => ({ ...entry, env: [...entry.env] })),
   discardSafeIncompleteMcpAdds: mocks.discardSafeIncompleteMcpAdds,
-  inspectExactMcpDestroyProvider: vi.fn(),
+  inspectExactMcpDestroyProvider: mocks.inspectExactMcpDestroyProvider,
 }));
 
 vi.mock("./mcp-bridge-policy", () => ({
@@ -118,6 +123,13 @@ describe("MCP adapter teardown rollback", () => {
       yaml: "version: 1\nnetwork_policies:\n  mcp_bridge_github: {}\n",
     });
     mocks.getSandboxOrThrow.mockReset().mockReturnValue(sandbox);
+    mocks.inspectExactMcpDestroyProvider.mockReset().mockReturnValue({
+      credentialKeys: ["GITHUB_TOKEN"],
+      exists: true,
+      id: entry.providerId,
+      resourceVersion: 12,
+      type: "nemoclaw-mcp-v1",
+    });
     mocks.inspectMcpProvider.mockReset().mockReturnValue({ exists: false });
     mocks.observeMcpCredentialRevision.mockReset().mockReturnValue("v12");
     mocks.removeGeneratedPolicy.mockReset().mockImplementation(() => {
@@ -176,4 +188,26 @@ describe("MCP adapter teardown rollback", () => {
     expect(mocks.unregisterAgentAdapter).not.toHaveBeenCalled();
     expect(mocks.registerAgentAdapterAtCurrentCredentialRevision).not.toHaveBeenCalled();
   });
+
+  it("recovers the recorded gateway before initial destroy provider inspection (#10514)", async () => {
+    const events: string[] = [];
+    mocks.ensureSandboxGatewaySelected.mockImplementation(async () => {
+      events.push("gateway-selected");
+    });
+    mocks.inspectExactMcpDestroyProvider.mockImplementation(() => {
+      events.push("provider-inspected");
+      return {
+        credentialKeys: ["GITHUB_TOKEN"],
+        exists: true,
+        id: entry.providerId,
+        resourceVersion: 12,
+        type: "nemoclaw-mcp-v1",
+      };
+    });
+
+    await expect(prepareMcpBridgesForDestroy("alpha")).rejects.toThrow(
+      "forced lifecycle failure after adapter scrub",
+    );
+    expect(events.slice(0, 2)).toEqual(["gateway-selected", "provider-inspected"]);
+  });
 });

src/lib/actions/sandbox/mcp-bridge-add-restart.ts

@@ -39,6 +39,7 @@ import {
   detachMissingProviderReference,
   detachProvider,
   ensureMcpBridgeProviderProfile,
+  getMcpProviderInspectionRuntimeSelection,
   inspectMcpProvider,
   type McpCredentialRevisionObservation,
   observeMcpCredentialRevision,
@@ -96,6 +97,7 @@ function assertPreparedMcpAddResourcesAbsent(
   adapter: AgentMcpAdapter,
   entry: McpBridgeEntry,
   target: McpBridgeTargetValidation,
+  providerRuntimeSelection: ReturnType<typeof getMcpProviderInspectionRuntimeSelection>,
 ): void {
   const adapterInspection = inspectAgentAdapterRegistration(sandboxName, adapter, entry);
   if (adapterInspection.state !== "absent") {
@@ -108,7 +110,7 @@ function assertPreparedMcpAddResourcesAbsent(
     );
   }
 
-  const providerInspection = inspectMcpProvider(entry.providerName);
+  const providerInspection = inspectMcpProvider(entry.providerName, providerRuntimeSelection);
   if (providerInspection.exists !== false) {
     const detail =
       providerInspection.exists === null
@@ -185,6 +187,7 @@ async function addMcpBridgeUnlocked(
   }
   const matchingTrustedPrivateHosts = allTrustedPrivateHosts.filter((host) => host === urlHost);
   const sandbox = getSandboxOrThrow(sandboxName);
+  const providerRuntimeSelection = getMcpProviderInspectionRuntimeSelection(sandbox);
   assertMcpDestroyNotPending(sandbox);
   const agent = getSandboxAgent(sandbox);
   const adapter = getBridgeAdapter(agent);
@@ -311,7 +314,7 @@ async function addMcpBridgeUnlocked(
       // Publish the durable MCP reservation under the same cross-command lock
       // used by credentials add. Neither command can pass its collision check
       // before the other records its credential-key reservation.
-      assertNoProviderCredentialCollisions(sandboxName, [entry]);
+      assertNoProviderCredentialCollisions(sandboxName, [entry], providerRuntimeSelection);
       writeBridgeEntry(sandboxName, entry);
     });
   }
@@ -323,7 +326,7 @@ async function addMcpBridgeUnlocked(
   try {
     let detachedMissingProviderReference = false;
     if (resumingPreflightedAdd) {
-      const providerInspection = inspectMcpProvider(entry.providerName);
+      const providerInspection = inspectMcpProvider(entry.providerName, providerRuntimeSelection);
       if (providerInspection.exists === null) {
         throw new McpBridgeError(
           providerInspection.error ??
@@ -337,7 +340,7 @@ async function addMcpBridgeUnlocked(
         // one recovery side effect that must precede the image capability
         // probe. It neither reads nor replaces credential material, and the
         // durable add manifest retains ownership if the later probe fails.
-        detachMissingProviderReference(sandboxName, entry);
+        detachMissingProviderReference(sandboxName, entry, providerRuntimeSelection);
         detachedMissingProviderReference = true;
       }
     }
@@ -350,15 +353,21 @@ async function addMcpBridgeUnlocked(
         // A retry may reuse an exact provider without re-exporting its secret,
         // but recreating a missing provider cannot. This check and any owned
         // policy cleanup happen only after the running-image capability probe.
-        assertMcpProviderRecoverable(entry);
+        assertMcpProviderRecoverable(entry, providerRuntimeSelection);
       } catch (error) {
         removeGeneratedPolicy(sandboxName, entry, { bestEffort: true });
         throw error;
       }
     }
 
     if (entry.addState === "prepared") {
-      assertPreparedMcpAddResourcesAbsent(sandboxName, adapter, entry, target);
+      assertPreparedMcpAddResourcesAbsent(
+        sandboxName,
+        adapter,
+        entry,
+        target,
+        providerRuntimeSelection,
+      );
       entry = { ...entry, addState: "preflighted" };
       // This second durable boundary proves the derived resource names and the
       // adapter slot were absent before any side effect. After a crash, retries
@@ -381,8 +390,8 @@ async function addMcpBridgeUnlocked(
     // Credential keys are sandbox-global. Prove this key is not already
     // supplied by a foreign attachment before opening its MCP route, then check
     // again after provider creation to close the intervening race.
-    assertNoProviderCredentialCollisions(sandboxName, [entry]);
-    ensureMcpBridgeProviderProfile();
+    assertNoProviderCredentialCollisions(sandboxName, [entry], providerRuntimeSelection);
+    ensureMcpBridgeProviderProfile(providerRuntimeSelection);
     // Load the real protocol:mcp policy without a credential binding before
     // provider mutation. OpenShell requires the endpointless provider to be
     // attached before it accepts credential_binding.provider, and withholds
@@ -395,6 +404,7 @@ async function addMcpBridgeUnlocked(
       // provider whose immutable ID was already persisted by this add.
       allowExisting: resumingPreflightedAdd,
       expectedProviderId: entry.providerId,
+      runtimeSelection: providerRuntimeSelection,
       prepareMutation: (action) => {
         // A fresh create has no prior revision to compare. Observe only the
         // bounded placeholder classification for an actual update, after the
@@ -418,14 +428,14 @@ async function addMcpBridgeUnlocked(
       // adapter mutations. A process death before this write fails closed.
       writeBridgeEntry(sandboxName, entry);
     }
-    assertNoProviderCredentialCollisions(sandboxName, [entry]);
+    assertNoProviderCredentialCollisions(sandboxName, [entry], providerRuntimeSelection);
     if (providerResult.action === "updated" && previousCredentialRevision === undefined) {
       throw new McpBridgeError(
         `Could not retain the prior OpenShell credential revision for provider '${entry.providerName}'.`,
       );
     }
     providerAttachAttempted = true;
-    attachProvider(sandboxName, entry);
+    attachProvider(sandboxName, entry, providerRuntimeSelection);
     applyGeneratedPolicy(sandboxName, entry, target);
     let refreshedAfterObservedAbsence = false;
     let credentialRevision = waitForAttachedMcpCredential(sandboxName, entry, {
@@ -455,8 +465,11 @@ async function addMcpBridgeUnlocked(
           allowExisting: true,
           expectedProviderId: entry.providerId,
           requireExisting: true,
+          runtimeSelection: providerRuntimeSelection,
         });
-        if (republished.action !== "updated") refreshMcpProviderEnvironment(entry);
+        if (republished.action !== "updated") {
+          refreshMcpProviderEnvironment(entry, providerRuntimeSelection);
+        }
       },
     });
     if (Object.hasOwn(adapterEnvValues, entry.env[0]) && !refreshedAfterObservedAbsence) {
@@ -469,6 +482,7 @@ async function addMcpBridgeUnlocked(
         allowExisting: true,
         expectedProviderId: entry.providerId,
         requireExisting: true,
+        runtimeSelection: providerRuntimeSelection,
       });
       credentialRevision = waitForAttachedMcpCredential(sandboxName, entry, {
         previousRevision: credentialRevision,
@@ -492,7 +506,7 @@ async function addMcpBridgeUnlocked(
   } catch (error) {
     const rollbackProviderInspection =
       (providerAttachAttempted || providerCreated) && entry.providerId
-        ? inspectMcpProvider(providerName)
+        ? inspectMcpProvider(providerName, providerRuntimeSelection)
         : undefined;
     const rollbackProviderOwned =
       !!rollbackProviderInspection &&
@@ -508,7 +522,10 @@ async function addMcpBridgeUnlocked(
       removeGeneratedPolicy(sandboxName, entry, { bestEffort: true });
     }
     const detachOutcome = providerAttachAttempted
-      ? detachProvider(sandboxName, entry, { bestEffort: true })
+      ? detachProvider(sandboxName, entry, {
+          bestEffort: true,
+          runtimeSelection: providerRuntimeSelection,
+        })
       : "absent";
     let reservationCleanupProved = !providerAttachAttempted;
     if (providerAttachAttempted && detachOutcome !== "unknown") {
@@ -520,9 +537,13 @@ async function addMcpBridgeUnlocked(
       }
     }
     if (providerCreated && rollbackProviderOwned && reservationCleanupProved) {
-      const beforeDelete = inspectMcpProvider(providerName);
+      const beforeDelete = inspectMcpProvider(providerName, providerRuntimeSelection);
       if (providerMatchesCredential(beforeDelete, entry.env[0], entry.providerId)) {
-        deleteProvider(entry, { allowMissing: true, bestEffort: true });
+        deleteProvider(entry, {
+          allowMissing: true,
+          bestEffort: true,
+          runtimeSelection: providerRuntimeSelection,
+        });
       }
     }
     // Exception rollback is best-effort and process death skips it entirely.