@@ -9,8 +9,20 @@ import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirec
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
 
-const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const updateSpy = vi.fn(() => Promise.resolve({ ...directory, name: 'Renamed' }));
+const rotateTokenSpy = vi.fn(() => Promise.resolve({ ...directory, token: 'tok_new' }));
+const deleteSpy = vi.fn(() => Promise.resolve({ object: 'directory', id: 'dir_1', deleted: true }));
+const directory = {
+  id: 'dir_1',
+  enterpriseConnectionId: 'ent_1',
+  update: updateSpy,
+  rotateToken: rotateTokenSpy,
+  delete: deleteSpy,
+};
 const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+const createDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string, _params?: unknown) =>
+  Promise.resolve({ ...directory, token: 'tok_1' }),
+);
 
 const defaultQueryClient = createMockQueryClient();
 
@@ -19,7 +31,7 @@ const mockClerk = createMockClerk({
   __internal_lastEmittedResources: {
     user: null,
     session: null,
-    organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+    organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy, createDirectorySync: createDirectorySyncSpy },
     client: null,
   },
 });
@@ -89,4 +101,96 @@ describe('useOrganizationDirectorySync', () => {
     expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
     expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
   });
+
+  describe('mutations', () => {
+    it('createDirectorySync creates for the connection, resolves the token-bearing resource, and refetches', async () => {
+      const { result } = renderDirectorySync();
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+      let created: Awaited<ReturnType<typeof result.current.createDirectorySync>>;
+      await act(async () => {
+        created = await result.current.createDirectorySync({ name: 'Okta' });
+      });
+
+      expect(createDirectorySyncSpy).toHaveBeenCalledWith('ent_1', { name: 'Okta' });
+      expect(created).toMatchObject({ id: 'dir_1', token: 'tok_1' });
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('createDirectorySync is a no-op without an enterprise connection id', async () => {
+      const { result } = renderDirectorySync(null);
+
+      await expect(result.current.createDirectorySync()).resolves.toBeUndefined();
+      expect(createDirectorySyncSpy).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      [
+        'updateDirectorySync',
+        updateSpy,
+        (r: ReturnType<typeof renderDirectorySync>['result']) => r.current.updateDirectorySync({ name: 'Renamed' }),
+      ],
+      [
+        'rotateDirectorySyncToken',
+        rotateTokenSpy,
+        (r: ReturnType<typeof renderDirectorySync>['result']) => r.current.rotateDirectorySyncToken(),
+      ],
+      [
+        'deleteDirectorySync',
+        deleteSpy,
+        (r: ReturnType<typeof renderDirectorySync>['result']) => r.current.deleteDirectorySync(),
+      ],
+    ] as const)('%s acts on the loaded directory and refetches it', async (_name, resourceSpy, run) => {
+      const { result } = renderDirectorySync();
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+      let resolved: unknown;
+      await act(async () => {
+        resolved = await run(result);
+      });
+
+      expect(resourceSpy).toHaveBeenCalledTimes(1);
+      expect(resolved).toBe(await resourceSpy.mock.results[0].value);
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('updateDirectorySync forwards its params to the resource', async () => {
+      const { result } = renderDirectorySync();
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+      await act(async () => {
+        await result.current.updateDirectorySync({ name: 'Renamed' });
+      });
+
+      expect(updateSpy).toHaveBeenCalledWith({ name: 'Renamed' });
+    });
+
+    it('directory-scoped mutations resolve undefined before the directory has loaded', async () => {
+      getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+      const { result } = renderDirectorySync();
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      expect(result.current.data).toBeNull();
+
+      await expect(result.current.updateDirectorySync({ name: 'Renamed' })).resolves.toBeUndefined();
+      await expect(result.current.rotateDirectorySyncToken()).resolves.toBeUndefined();
+      await expect(result.current.deleteDirectorySync()).resolves.toBeUndefined();
+      expect(updateSpy).not.toHaveBeenCalled();
+      expect(rotateTokenSpy).not.toHaveBeenCalled();
+      expect(deleteSpy).not.toHaveBeenCalled();
+    });
+
+    it('propagates a failed mutation and skips the refetch', async () => {
+      const { result } = renderDirectorySync();
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+      const failure = new Error('rotate failed');
+      rotateTokenSpy.mockRejectedValueOnce(failure);
+
+      await expect(result.current.rotateDirectorySyncToken()).rejects.toBe(failure);
+      expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+    });
+  });
 });
@@ -67,6 +67,10 @@ describe('useOrganizationDirectorySyncUsers', () => {
 
     act(() => result.current.stopPolling());
     expect(result.current.isPolling).toBe(false);
+
+    const callsAfterStop = getUsersSpy.mock.calls.length;
+    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS * 3));
+    expect(getUsersSpy.mock.calls.length).toBe(callsAfterStop);
   });
 
   it('disarms polling when the directory identity changes', async () => {
@@ -80,6 +84,23 @@ describe('useOrganizationDirectorySyncUsers', () => {
     expect(result.current.isPolling).toBe(false);
   });
 
+  it('does not resume polling when the original directory returns', async () => {
+    const { result, rerender } = renderUsers(createDirectory('dir_1'));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    act(() => result.current.startPolling());
+    expect(result.current.isPolling).toBe(true);
+
+    rerender({ directory: createDirectory('dir_2') });
+    rerender({ directory: createDirectory('dir_1') });
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isPolling).toBe(false);
+
+    const callsAfterReturn = getUsersSpy.mock.calls.length;
+    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS * 3));
+    expect(getUsersSpy.mock.calls.length).toBe(callsAfterReturn);
+  });
+
   it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
     let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
 
 
@@ -166,4 +166,28 @@ describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', ()
     rerender({ enterpriseConnectionId: 'ent_2' });
     expect(result.current.isPolling).toBe(false);
   });
+
+  it('does not resume polling when the original connection returns without a new revalidate', async () => {
+    getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+    const { result, rerender } = renderHook(
+      ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+        __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+      { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.revalidate();
+    });
+    expect(result.current.isPolling).toBe(true);
+
+    rerender({ enterpriseConnectionId: 'ent_2' });
+    rerender({ enterpriseConnectionId: 'ent_1' });
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isPolling).toBe(false);
+
+    const callsAfterReturn = getTestRunsSpy.mock.calls.length;
+    await new Promise(resolve => setTimeout(resolve, 60));
+    expect(getTestRunsSpy.mock.calls.length).toBe(callsAfterReturn);
+  });
 });
@@ -20,11 +20,7 @@ export type UseOrganizationDirectorySyncParams = {
 };
 
 export type UseOrganizationDirectorySyncReturn = {
-  /**
-   * The connection's directory, `null` when none has been created yet, `undefined` while loading.
-   * Never carries the bearer token — that only exists on the resources resolved by
-   * `createDirectorySync` and `rotateDirectorySyncToken`.
-   */
+  /** The connection's directory, `null` when none has been created yet, `undefined` while loading. */
   data: DirectorySyncResource | null | undefined;
   error: Error | null;
   isLoading: boolean;
 
@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 
 import type {
   DirectorySyncResource,
@@ -15,21 +15,21 @@ import { useOrganizationDirectorySyncUsersCacheKeys } from './useOrganizationDir
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 
 export type UseOrganizationDirectorySyncUsersParams = {
-  /** The directory to list users for, e.g. `data` from `useOrganizationDirectorySync`. Dormant while nullish. */
+  /** The directory to list users for, e.g. `data` from `useOrganizationDirectorySync`. Nothing is fetched while `null` or `undefined`. */
   directory: DirectorySyncResource | null | undefined;
   /**
    * Pass-through fetch parameters (pagination).
    * Defaults to `{ initialPage: 1, pageSize: 10 }`.
    */
   params?: GetDirectorySyncUsersParams;
   /**
-   * Polling interval (ms) applied while polling is armed via `startPolling`.
+   * Polling interval (ms) used while polling is active.
    *
    * @default 2000
    */
   pollIntervalMs?: number;
   /**
-   * If `false`, the hook is dormant — no fetch, no polling.
+   * If `false`, nothing is fetched and polling is paused.
    *
    * @default true
    */
@@ -38,25 +38,21 @@ export type UseOrganizationDirectorySyncUsersParams = {
 };
 
 export type UseOrganizationDirectorySyncUsersReturn = {
-  /** `undefined` while loading and while the hook is dormant. */
+  /** `undefined` while loading and while the hook is disabled. */
   data: DirectorySyncUserResource[] | undefined;
   totalCount: number | undefined;
   error: Error | null;
   isLoading: boolean;
   isFetching: boolean;
-  /**
-   * `true` while the hook is actively polling
-   */
+  /** `true` while the hook is polling. */
   isPolling: boolean;
   /**
-   * Start polling. Polling runs continuously (new provisions, updates, and
-   * deprovisions keep appearing) until `stopPolling` is called — callers
-   * should stop on unmount of the view that armed it.
+   * Start polling for changes to the list. Polling continues until `stopPolling`
+   * is called or the hook unmounts, so colocate the hook with the view that
+   * needs the feed and call this from an effect on mount.
    */
   startPolling: () => void;
-  /**
-   * Stop polling.
-   */
+  /** Stop polling. */
   stopPolling: () => void;
   /**
    * Force a refetch.
@@ -66,8 +62,8 @@ export type UseOrganizationDirectorySyncUsersReturn = {
 
 /**
  * The users provisioned into an enterprise connection's Directory Sync
- * directory, most recently touched first. Polls continuously while armed via
- * `startPolling`, so the setup flow doubles as a recent-activity feed.
+ * directory, most recently touched first. Polling is opt-in via `startPolling`,
+ * which lets the setup flow use the list as a live activity feed.
  *
  * @internal
  */
@@ -103,10 +99,16 @@ function useOrganizationDirectorySyncUsers(
 
   const queryEnabled = enabled && clerk.loaded && Boolean(organization) && Boolean(directory);
 
-  // Polling is armed for a specific directory and derived, not reset in an effect: a child
-  // effect arming it in the same commit the directory arrives would otherwise be cancelled.
-  const [armedForDirectoryId, setArmedForDirectoryId] = useState<string | null>(null);
-  const shouldPoll = armedForDirectoryId !== null && armedForDirectoryId === directoryId;
+  // Polling is requested for a specific directory, so a directory change stops it. This is
+  // derived rather than reset in an effect because a child component may call `startPolling`
+  // in the same commit the directory arrives, and an unconditional reset would cancel that.
+  const [pollingDirectoryId, setPollingDirectoryId] = useState<string | null>(null);
+  const shouldPoll = pollingDirectoryId !== null && pollingDirectoryId === directoryId;
+
+  useEffect(() => {
+    // Drop a request left over from a previous directory so it cannot resume if that directory returns.
+    setPollingDirectoryId(current => (current !== null && current !== directoryId ? null : current));
+  }, [directoryId]);
 
   const currentTracked = queryKey[2];
   const query = useClerkQuery({
@@ -137,11 +139,11 @@ function useOrganizationDirectorySyncUsers(
   });
 
   const startPolling = useCallback(() => {
-    setArmedForDirectoryId(directoryId);
+    setPollingDirectoryId(directoryId);
   }, [directoryId]);
 
   const stopPolling = useCallback(() => {
-    setArmedForDirectoryId(null);
+    setPollingDirectoryId(null);
   }, []);
 
   const revalidate = useCallback(async () => {
@@ -151,7 +153,7 @@ function useOrganizationDirectorySyncUsers(
   const isPolling = queryEnabled && shouldPoll;
 
   return {
-    // Dormant means dormant: never surface cached rows while the query cannot run.
+    // A disabled query still exposes rows cached under its key; report none until it can run.
     data: queryEnabled ? query.data?.data : undefined,
     totalCount: queryEnabled ? query.data?.total_count : undefined,
     error: query.error ?? null,
 
@@ -136,10 +136,16 @@ function useOrganizationEnterpriseConnectionTestRuns(
 
   const queryEnabled = enabled && clerk.loaded && Boolean(organization) && Boolean(enterpriseConnectionId);
 
-  // Polling is armed for a specific connection and derived, not reset in an effect: a child
-  // effect arming it in the same commit the connection arrives would otherwise be cancelled.
-  const [armedForConnectionId, setArmedForConnectionId] = useState<string | null>(null);
-  const shouldPoll = armedForConnectionId !== null && armedForConnectionId === enterpriseConnectionId;
+  // Polling is requested for a specific connection, so a connection change stops it. This is
+  // derived rather than reset in an effect because a child component may call `revalidate` in
+  // the same commit the connection arrives, and an unconditional reset would cancel that.
+  const [pollingConnectionId, setPollingConnectionId] = useState<string | null>(null);
+  const shouldPoll = pollingConnectionId !== null && pollingConnectionId === enterpriseConnectionId;
+
+  useEffect(() => {
+    // Drop a request left over from a previous connection so it cannot resume if that connection returns.
+    setPollingConnectionId(current => (current !== null && current !== enterpriseConnectionId ? null : current));
+  }, [enterpriseConnectionId]);
 
   const query = useClerkQuery({
     queryKey,
@@ -166,7 +172,7 @@ function useOrganizationEnterpriseConnectionTestRuns(
 
   useEffect(() => {
     if (shouldPoll && hasRows) {
-      setArmedForConnectionId(null);
+      setPollingConnectionId(null);
     }
   }, [shouldPoll, hasRows]);
 
@@ -181,7 +187,7 @@ function useOrganizationEnterpriseConnectionTestRuns(
       // off. Once any record has been seen, this is a one-shot refetch.
       const armPolling = options?.armPolling ?? true;
       if (armPolling && !hasRows) {
-        setArmedForConnectionId(enterpriseConnectionId);
+        setPollingConnectionId(enterpriseConnectionId);
       }
       // `invalidateQueries` awaits the refetch it triggers, so by the time it
       // resolves the cache already holds the fresh page. Read it back from the